@kontextmind/kxm 0.7.0 → 0.7.5

package/plugins/kxm/dist/runtime.js

@@ -15122,6 +15122,19 @@ var OUTPUT_LIMIT = 8 * 1024 * 1024;
 var KILL_GRACE_MS = 250;
 var DRAIN_GRACE_MS = 500;
 var REAP_GRACE_MS = 1e3;
+function killProcessTree(child, signal = "SIGKILL") {
+  if (process.platform !== "win32" && child.pid) {
+    try {
+      process.kill(-child.pid, signal);
+      return;
+    } catch {
+    }
+  }
+  try {
+    child.kill(signal);
+  } catch {
+  }
+}
 function defaultSpawn(command, args, options) {
   if (options.signal?.aborted) {
     return Promise.resolve({ stdout: "", stderr: "", code: null, started: false, observedChildExit: false, error: new Error("process_aborted") });
@@ -15158,11 +15171,7 @@ function defaultSpawn(command, args, options) {
       resolve8({ stdout: Buffer.concat(stdout).toString("utf8"), stderr: Buffer.concat(stderr).toString("utf8"), code, signal, started, observedChildExit, terminationRequested: stopping, ...error ? { error } : {} });
     };
     const kill = (requested) => {
-      try {
-        if (process.platform !== "win32" && child.pid) process.kill(-child.pid, requested);
-        else child.kill(requested);
-      } catch {
-      }
+      killProcessTree(child, requested);
     };
     const stop = (reason) => {
       if (finished) return;
@@ -15489,7 +15498,9 @@ function parseAgyOneShotUsage(stdout, _stderr) {
 var READ_ONLY_ONESHOT_ARGS = Object.freeze({
   claude: Object.freeze(["--tools", "Read,Glob,Grep", "--restricted", "--safe-mode", "--strict-mcp-config", "--mcp-config", '{"mcpServers":{}}', "--disable-slash-commands", "--no-session-persistence"]),
   codex: Object.freeze(["--sandbox", "read-only", "--ignore-user-config", "-c", 'approval_policy="never"']),
-  grok: Object.freeze(["--sandbox", "read-only", "--permission-mode", "plan", "--tools", "Read,Glob,Grep", "--no-subagents", "--disable-web-search"])
+  grok: Object.freeze(["--sandbox", "read-only", "--permission-mode", "plan", "--tools", "Read,Glob,Grep", "--no-subagents", "--disable-web-search"]),
+  agy: Object.freeze(["--mode", "plan", "--sandbox", "--disable-slash-commands"]),
+  kimi: Object.freeze(["--plan"])
 });
 function oneShotReadOnlyArgs(harness) {
   return Object.hasOwn(READ_ONLY_ONESHOT_ARGS, harness) ? READ_ONLY_ONESHOT_ARGS[harness] : void 0;
@@ -15543,7 +15554,7 @@ var BUILTIN_HARNESSES = Object.freeze([
     authArgs: ["provider", "list"],
     update: { self: ["upgrade"] },
     oneShot: {
-      argv: ["--output-format", "stream-json", "-p"],
+      argv: [...oneShotReadOnlyArgs("kimi"), "--output-format", "stream-json", "-p"],
       promptVia: "arg",
       outputFormat: "stream-json",
       usageParser: parseKimiOneShotUsage
@@ -15606,7 +15617,7 @@ var BUILTIN_HARNESSES = Object.freeze([
     authArgs: ["models"],
     update: { self: ["update"] },
     oneShot: {
-      argv: ["--output-format", "json", "-p"],
+      argv: [...oneShotReadOnlyArgs("agy"), "--output-format", "json", "-p"],
       promptVia: "arg",
       outputFormat: "json",
       usageParser: parseAgyOneShotUsage
@@ -17060,7 +17071,7 @@ function validateModelReferences(models, issues) {
   };
   for (const id of models.keys()) walk(id, []);
 }
-function validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry) {
+function validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, projectRoot) {
   const issues = [];
   const entries = valuesOf(project.value, "repositories").map((candidate) => objectValue(candidate)).filter((candidate) => Boolean(candidate));
   const repositoryIds = /* @__PURE__ */ new Set();
@@ -17128,6 +17139,33 @@ function validateBundle(project, repositories, agents, models, workflows, enviro
   const defaultWorkflow = stringValue(project.value.defaultWorkflow) ?? "default";
   if (!workflows.has(defaultWorkflow)) issues.push(issue2("reference", "default_workflow_unknown", project.logicalPath, `default workflow ${defaultWorkflow} does not exist`));
   for (const workflow of workflows.values()) validateWorkflow(workflow, agents, models, repositoryIds, gates, issues);
+  if (projectRoot) {
+    const writerRolePath = join(projectRoot, ".kxm", "roles", "writer.yaml");
+    const implementerAgent = agents.get("implementer") ?? agents.get("writer");
+    if (existsSync2(writerRolePath) && implementerAgent) {
+      try {
+        const rawRole = parseRestrictedYaml2(readFileSync(writerRolePath, "utf8"));
+        const roleObj = objectValue(rawRole);
+        const rosterEntries = valuesOf(roleObj ?? {}, "roster").map((candidate) => objectValue(candidate)).filter((entry) => Boolean(entry));
+        const enabledRosterModels = rosterEntries.filter((entry) => entry.enabled !== false).map((entry) => stringValue(entry.model)).filter((m) => Boolean(m));
+        const agentModelObj = objectValue(implementerAgent.value.model);
+        const agentModelStr = stringValue(implementerAgent.value.model);
+        const agentProvider = agentModelObj ? stringValue(agentModelObj.provider) : void 0;
+        const agentModel = agentModelObj ? stringValue(agentModelObj.model) : agentModelStr;
+        const canonicalAgentModel = agentProvider && agentModel ? `${agentProvider}/${agentModel}` : agentModel;
+        if (enabledRosterModels.length > 0 && canonicalAgentModel) {
+          const matches = enabledRosterModels.some((rm) => rm === canonicalAgentModel || rm === agentModel || rm.endsWith(`/${agentModel}`));
+          if (!matches) {
+            issues.push(issue2("semantic", "role_roster_conflicts_with_agent", ".kxm/roles/writer.yaml", `role roster in .kxm/roles/writer.yaml does not include agent model ${canonicalAgentModel} from ${implementerAgent.logicalPath}`));
+          }
+        }
+      } catch (error) {
+        if (error instanceof VnextConfigError) {
+          issues.push(...error.issues);
+        }
+      }
+    }
+  }
   return sortIssues2(issues);
 }
 function vnextCanonicalJson(value) {
@@ -17308,7 +17346,7 @@ function loadVnextProject(projectRoot, options = {}) {
     }
   }
   if (loadIssues.length > 0) throw new VnextConfigError(loadIssues);
-  const issues = validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry);
+  const issues = validateBundle(project, repositories, agents, models, workflows, environments, options, gateRegistry, root);
   if (issues.length > 0) throw new VnextConfigError(issues);
   const resources = [project, ...repositories.values(), ...agents.values(), ...models.values(), ...workflows.values(), ...environments, ...gateRegistry ? [gateRegistry] : []].sort((left, right) => compareCodeUnits3(left.logicalPath, right.logicalPath));
   return {
@@ -17420,7 +17458,47 @@ import { dirname as dirname4, join as join4, resolve as resolve4 } from "node:pa
 
 // plugins/kxm/src/vnext-bindings.ts
 import { homedir } from "node:os";
-import { DatabaseSync } from "node:sqlite";
+
+// plugins/kxm/src/sqlite.ts
+import { createRequire } from "node:module";
+var requireFromHere = createRequire(import.meta.url);
+function loadNative() {
+  try {
+    const mod = requireFromHere("node:sqlite");
+    if (mod.DatabaseSync) return { Ctor: mod.DatabaseSync, bun: false };
+  } catch {
+  }
+  try {
+    const mod = requireFromHere("bun:sqlite");
+    const Ctor = mod?.DatabaseSync ?? mod?.Database;
+    if (Ctor) return { Ctor, bun: true };
+  } catch {
+  }
+  throw new Error("kxm: no supported sqlite module found (need node:sqlite or bun:sqlite)");
+}
+var native = loadNative();
+var DatabaseSync = class {
+  inner;
+  constructor(path, options) {
+    let normalized = options;
+    if (native.bun && options) {
+      const { readOnly, ...rest } = options;
+      normalized = readOnly === void 0 ? rest : { ...rest, readonly: readOnly };
+    }
+    this.inner = normalized === void 0 ? new native.Ctor(path) : new native.Ctor(path, normalized);
+  }
+  prepare(sql) {
+    return this.inner.prepare(sql);
+  }
+  exec(sql) {
+    return this.inner.exec(sql);
+  }
+  close() {
+    this.inner.close();
+  }
+};
+
+// plugins/kxm/src/vnext-bindings.ts
 import { dirname as dirname2, isAbsolute as isAbsolute2, join as join2, parse, relative as relative2, resolve as resolve2, sep as sep2 } from "node:path";
 var MAX_BINDING_RECORD_BYTES = 256 * 1024;
 var BINDING_LABEL = "Runtime-local repository bindings";
@@ -17464,7 +17542,6 @@ import {
   writeFileSync
 } from "node:fs";
 import { basename as basename2, dirname as dirname3, join as join3, resolve as resolve3 } from "node:path";
-import { DatabaseSync as DatabaseSync2 } from "node:sqlite";
 function databaseError(code, file, message) {
   const issue3 = { phase: "semantic", code, file, message };
   return new VnextConfigError([issue3]);
@@ -17544,7 +17621,7 @@ function openDatabase(file, description, spec) {
       }
     }
   }
-  const database = new DatabaseSync2(file);
+  const database = new DatabaseSync(file);
   let transaction = false;
   try {
     database.exec(`PRAGMA busy_timeout = ${spec.timeoutMs ?? 5e3}`);
@@ -17648,7 +17725,7 @@ function backupDatabaseFile(sourcePath, targetPath, storeId) {
   if (existsSync3(resolvedTarget)) {
     unlinkSync(resolvedTarget);
   }
-  const sourceDb = new DatabaseSync2(resolvedSource);
+  const sourceDb = new DatabaseSync(resolvedSource);
   let schemaVersion = 0;
   try {
     sourceDb.exec("PRAGMA busy_timeout = 5000");
@@ -17663,7 +17740,7 @@ function backupDatabaseFile(sourcePath, targetPath, storeId) {
   } finally {
     sourceDb.close();
   }
-  const targetDb = new DatabaseSync2(resolvedTarget);
+  const targetDb = new DatabaseSync(resolvedTarget);
   try {
     targetDb.exec("PRAGMA busy_timeout = 5000");
     if (!checkIntegrity(targetDb)) {
@@ -17695,7 +17772,7 @@ function restoreDatabaseFile(backupPath, targetPath, storeId, expectedSchemaVers
   if (!backupStat || !backupStat.isFile() || backupStat.isSymbolicLink()) {
     throw databaseError("runtime_path_invalid", resolvedBackup, `backup database ${resolvedBackup} must be a regular file, not a link or directory`);
   }
-  const backupDb = new DatabaseSync2(resolvedBackup);
+  const backupDb = new DatabaseSync(resolvedBackup);
   let schemaVersion = 0;
   try {
     backupDb.exec("PRAGMA busy_timeout = 5000");
@@ -17735,7 +17812,7 @@ function restoreDatabaseFile(backupPath, targetPath, storeId, expectedSchemaVers
     chmodSync(resolvedTarget, 384);
   } catch {
   }
-  const targetDb = new DatabaseSync2(resolvedTarget);
+  const targetDb = new DatabaseSync(resolvedTarget);
   try {
     targetDb.exec("PRAGMA busy_timeout = 5000");
     if (!checkIntegrity(targetDb)) {
@@ -22912,6 +22989,32 @@ function evaluateArtifactsGate(context, definition) {
 // plugins/kxm/src/vnext-engine-command.ts
 import { spawn as spawn2 } from "node:child_process";
 import { createHash as createHash9 } from "node:crypto";
+
+// plugins/kxm/src/safety-integrity.ts
+var DESTRUCTIVE_COMMAND_PATTERNS = Object.freeze([
+  /^\s*rm\s+.*-[a-zA-Z]*r[a-zA-Z]*f/i,
+  /^\s*rm\s+.*-[a-zA-Z]*f[a-zA-Z]*r/i,
+  /^\s*rm\s+.*(-[a-zA-Z]*r[a-zA-Z]*\s+.*-[a-zA-Z]*f[a-zA-Z]*|-[a-zA-Z]*f[a-zA-Z]*\s+.*-[a-zA-Z]*r[a-zA-Z]*)/i,
+  /^\s*git\s+reset\s+--hard/i,
+  /^\s*git\s+clean\s+-[a-zA-Z]*f/i,
+  /^\s*git\s+checkout\s+--\s+/i,
+  /^\s*git\s+restore\s+(\.|\*|--staged\s+(\.|\*))/i
+]);
+function assertCommandSeatbelt(command) {
+  for (const pattern of DESTRUCTIVE_COMMAND_PATTERNS) {
+    if (pattern.test(command)) {
+      throw new Error(
+        `Command blocked by KXM safety seatbelt: "${command}". Destructive workspace mutations require explicit operator override.`
+      );
+    }
+  }
+}
+var INSECURE_SSH_HOST_KEY_PATTERNS = Object.freeze([
+  /StrictHostKeyChecking=(accept-new|no|off)/i,
+  /UserKnownHostsFile=\/dev\/null/i
+]);
+
+// plugins/kxm/src/vnext-engine-command.ts
 var MAX_DIRECT_TIMER_MS = 2147483647;
 var COMMAND_TERM_GRACE_MS = 2e3;
 var COMMAND_FINAL_WAIT_MS = 2e3;
@@ -23028,6 +23131,7 @@ var CommandObserver = class {
     if (!Number.isInteger(this.definition.timeoutMs) || this.definition.timeoutMs < 1 || this.definition.timeoutMs > MAX_DIRECT_TIMER_MS) {
       throw runtimeError("run_events_illegal", "command", "command timeoutMs exceeds the direct timer bound");
     }
+    assertCommandSeatbelt(this.definition.argv.join(" "));
     this.startedAt = (/* @__PURE__ */ new Date()).toISOString();
     let child;
     try {
@@ -24153,6 +24257,7 @@ async function stepLocked(context, runId, producer, token) {
   return drivePanel(context, prepared.panel, producer);
 }
 async function runPreparedCommandGate(context, prepared, definition, token) {
+  assertCommandSeatbelt(definition.argv.join(" "));
   const storePath = context.eventStore.path;
   const observer = createCommandObserver({
     definition,
@@ -25930,6 +26035,24 @@ function createVnextOneShotProducer(options = {}) {
         "--output-format",
         "json"
       ];
+    } else if (harness === "agy") {
+      args = [
+        "-m",
+        resolved.model,
+        ...permissionArgs,
+        "--output-format",
+        "json",
+        "-p"
+      ];
+    } else if (harness === "kimi") {
+      args = [
+        "-m",
+        resolved.model,
+        ...permissionArgs,
+        "--output-format",
+        "stream-json",
+        "-p"
+      ];
     } else {
       throw new Error(`oneshot_harness_unsupported: ${harness} permission_profile_unaudited`);
     }
@@ -27627,6 +27750,429 @@ function evaluatePromotionPolicy(candidate, policy = "manual_pr", options) {
     reason: `Unknown promotion policy: ${String(policy)}`
   };
 }
+
+// plugins/kxm/src/browser.ts
+import { execSync } from "node:child_process";
+var VIEWPORT_PRESETS = Object.freeze({
+  "mobile-sm": { name: "Mobile Small (SE)", category: "mobile", width: 375, height: 667, isMobile: true, hasTouch: true },
+  "mobile": { name: "Mobile (iPhone 16 / 15 Pro)", category: "mobile", width: 393, height: 852, isMobile: true, hasTouch: true },
+  "mobile-lg": { name: "Mobile Large (Pro Max)", category: "mobile", width: 430, height: 932, isMobile: true, hasTouch: true },
+  "pixel": { name: "Google Pixel 8/9", category: "mobile", width: 412, height: 924, isMobile: true, hasTouch: true },
+  "galaxy": { name: "Samsung Galaxy S24", category: "mobile", width: 360, height: 780, isMobile: true, hasTouch: true },
+  "tablet": { name: "Tablet (iPad Air / Mini)", category: "tablet", width: 820, height: 1180, isMobile: true, hasTouch: true },
+  "tablet-lg": { name: "Tablet Large (iPad Pro 12.9)", category: "tablet", width: 1024, height: 1366, isMobile: true, hasTouch: true },
+  "laptop": { name: "Standard Laptop", category: "laptop", width: 1366, height: 768 },
+  "macbook-13": { name: "MacBook Air 13", category: "laptop", width: 1440, height: 900 },
+  "macbook-16": { name: "MacBook Pro 16", category: "laptop", width: 1728, height: 1117 },
+  "desktop": { name: "Desktop FHD (1080p)", category: "desktop", width: 1920, height: 1080 },
+  "desktop-2k": { name: "Desktop QHD (1440p)", category: "desktop", width: 2560, height: 1440 },
+  "desktop-4k": { name: "Desktop 4K UHD", category: "desktop", width: 3840, height: 2160 }
+});
+function resolveViewportDimensions(presetOrDims) {
+  if (!presetOrDims) {
+    return { width: 1920, height: 1080 };
+  }
+  if (typeof presetOrDims === "string") {
+    const matched = VIEWPORT_PRESETS[presetOrDims.toLowerCase()];
+    if (matched) {
+      return { width: matched.width, height: matched.height };
+    }
+    return { width: 1920, height: 1080 };
+  }
+  return presetOrDims;
+}
+function resolvePassCliApiKey(execFn = (cmd) => execSync(cmd, { encoding: "utf8", stdio: ["pipe", "pipe", "ignore"], timeout: 5e3 })) {
+  if (typeof process === "undefined" || process.env.USE_PASS_CLI === "false") {
+    return void 0;
+  }
+  if (process.env.PASS_CLI_OUTPUT_MOCK) {
+    try {
+      const parsed = JSON.parse(process.env.PASS_CLI_OUTPUT_MOCK);
+      const extraFields = parsed?.item?.content?.extra_fields || [];
+      const customSections = parsed?.item?.content?.content?.Custom?.sections || [];
+      const sectionFields = customSections.flatMap((s) => s.section_fields || []);
+      const allFields = [...extraFields, ...sectionFields];
+      return allFields.find((f) => f.name === "STEEL_API_KEY")?.content?.Hidden;
+    } catch {
+      return void 0;
+    }
+  }
+  try {
+    const output = execFn(
+      'pass-cli item view --vault-name "AI Provider Keys" --item-title "Steel Browser (KontextMind DOKS)" --output json'
+    );
+    const parsed = JSON.parse(output);
+    const extraFields = parsed?.item?.content?.extra_fields || [];
+    const customSections = parsed?.item?.content?.content?.Custom?.sections || [];
+    const sectionFields = customSections.flatMap((s) => s.section_fields || []);
+    const allFields = [...extraFields, ...sectionFields];
+    return allFields.find((f) => f.name === "STEEL_API_KEY")?.content?.Hidden;
+  } catch {
+    return void 0;
+  }
+}
+function resolveSteelConfig(overrides) {
+  const apiUrl = overrides?.apiUrl || process.env.STEEL_API_URL || "https://steel.kontextmind.com";
+  const apiKey = overrides?.apiKey || process.env.STEEL_API_KEY || resolvePassCliApiKey();
+  const uiUrl = overrides?.uiUrl || (overrides?.apiUrl ? `${overrides.apiUrl.replace(/\/$/, "")}/ui` : void 0) || process.env.STEEL_UI_URL || `${apiUrl.replace(/\/$/, "")}/ui`;
+  return {
+    apiUrl: apiUrl.replace(/\/$/, ""),
+    apiKey,
+    uiUrl,
+    timeoutMs: overrides?.timeoutMs || 3e5
+    // 5 minutes default
+  };
+}
+function formatCDPEndpoint(session, config) {
+  const baseApi = config.apiUrl;
+  const urlObj = new URL(baseApi);
+  const isSecure = urlObj.protocol === "https:";
+  const wsProtocol = isSecure ? "wss:" : "ws:";
+  const host = urlObj.host;
+  const searchParams = new URLSearchParams();
+  searchParams.set("sessionId", session.id);
+  if (config.apiKey) {
+    searchParams.set("apiKey", config.apiKey);
+  }
+  return `${wsProtocol}//${host}/v1/devtools?${searchParams.toString()}`;
+}
+function sanitizeLogOutput(input) {
+  if (typeof input === "string") {
+    return input.replace(/apiKey=[^&]+/g, "apiKey=[REDACTED]").replace(/steel_[a-f0-9]+/g, "steel_[REDACTED]");
+  }
+  if (Array.isArray(input)) {
+    return input.map(sanitizeLogOutput);
+  }
+  if (input !== null && typeof input === "object") {
+    const copy = {};
+    for (const [k, v] of Object.entries(input)) {
+      if (/key|secret|token|auth|password/i.test(k) && typeof v === "string") {
+        copy[k] = "[REDACTED]";
+      } else {
+        copy[k] = sanitizeLogOutput(v);
+      }
+    }
+    return copy;
+  }
+  return input;
+}
+function createAnnotationFeedback(feedback) {
+  return {
+    ...feedback,
+    capturedAt: feedback.capturedAt || (/* @__PURE__ */ new Date()).toISOString()
+  };
+}
+function formatAnnotationFeedbackPrompt(feedback) {
+  let output = `## Visual Feedback & Section Annotation
+
+`;
+  output += `- **Target URL**: ${feedback.url}
+`;
+  if (feedback.sessionId) {
+    output += `- **Session ID**: ${feedback.sessionId}
+`;
+  }
+  if (feedback.sectionSelector) {
+    output += `- **Section Target Selector**: \`${feedback.sectionSelector}\`
+`;
+  }
+  if (feedback.screenshotPath) {
+    output += `- **Screenshot Artifact**: \`${feedback.screenshotPath}\`
+`;
+  }
+  output += `- **Captured At**: ${feedback.capturedAt}
+
+`;
+  output += `### Summary
+${feedback.overallSummary}
+
+`;
+  if (feedback.annotations.length > 0) {
+    output += `### Annotated Elements & Notes
+
+`;
+    feedback.annotations.forEach((item, idx) => {
+      output += `${idx + 1}. **${item.label}**`;
+      if (item.severity) {
+        output += ` [${item.severity.toUpperCase()}]`;
+      }
+      output += `
+   - **Note**: ${item.note}
+`;
+      if (item.selector) {
+        output += `   - **Selector**: \`${item.selector}\`
+`;
+      }
+      if (item.boundingBox) {
+        output += `   - **Region (Box)**: x=${item.boundingBox.x}, y=${item.boundingBox.y}, w=${item.boundingBox.width}, h=${item.boundingBox.height}
+`;
+      }
+    });
+    output += `
+`;
+  }
+  if (feedback.requestedChanges.length > 0) {
+    output += `### Actionable Change List
+
+`;
+    feedback.requestedChanges.forEach((change, idx) => {
+      output += `- [ ] ${change}
+`;
+    });
+  }
+  return output;
+}
+var SteelClient = class {
+  config;
+  activeSessions = /* @__PURE__ */ new Map();
+  constructor(config) {
+    this.config = resolveSteelConfig(config);
+  }
+  getConfig() {
+    return { ...this.config };
+  }
+  headers() {
+    const h = {
+      "Content-Type": "application/json"
+    };
+    if (this.config.apiKey) {
+      h["x-steel-api-key"] = this.config.apiKey;
+    }
+    return h;
+  }
+  /**
+   * Launch a new Steel browser session on DOKS.
+   */
+  async createSession(options) {
+    const timeoutMs = options?.timeoutMs ?? this.config.timeoutMs ?? 3e5;
+    const body = {
+      timeout: timeoutMs
+    };
+    const dimensions = options?.dimensions || (options?.viewportPreset ? resolveViewportDimensions(options.viewportPreset) : void 0);
+    if (dimensions) {
+      body.dimensions = dimensions;
+    }
+    if (options?.userAgent) {
+      body.userAgent = options.userAgent;
+    }
+    if (options?.proxy) {
+      body.proxy = options.proxy;
+    }
+    const res = await fetch(`${this.config.apiUrl}/v1/sessions`, {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) {
+      const errText = await res.text();
+      throw new Error(`Failed to create Steel session (${res.status}): ${errText}`);
+    }
+    const data = await res.json();
+    const session = {
+      id: data.id,
+      createdAt: data.createdAt || (/* @__PURE__ */ new Date()).toISOString(),
+      status: "live",
+      state: "AGENT_CONTROL",
+      websocketUrl: data.websocketUrl || "",
+      debugUrl: data.debugUrl || "",
+      debuggerUrl: data.debuggerUrl || "",
+      sessionViewerUrl: data.sessionViewerUrl || `${this.config.uiUrl}?sessionId=${data.id}`,
+      timeoutMs,
+      lastActiveAt: Date.now(),
+      activeController: "agent",
+      userAgent: data.userAgent
+    };
+    this.activeSessions.set(session.id, session);
+    return session;
+  }
+  /**
+   * Get details of an existing session.
+   */
+  async getSession(sessionId) {
+    const res = await fetch(`${this.config.apiUrl}/v1/sessions/${encodeURIComponent(sessionId)}`, {
+      method: "GET",
+      headers: this.headers()
+    });
+    if (res.status === 404) {
+      const cached = this.activeSessions.get(sessionId);
+      if (cached) {
+        cached.state = "EXPIRED";
+        cached.status = "released";
+        cached.activeController = "none";
+      }
+      return null;
+    }
+    if (!res.ok) {
+      throw new Error(`Failed to fetch Steel session (${res.status})`);
+    }
+    const data = await res.json();
+    const existing = this.activeSessions.get(sessionId);
+    const session = {
+      id: data.id,
+      createdAt: data.createdAt,
+      status: data.status,
+      state: existing?.state ?? (data.status === "live" ? "AGENT_CONTROL" : "RELEASED"),
+      websocketUrl: data.websocketUrl || existing?.websocketUrl || "",
+      debugUrl: data.debugUrl || existing?.debugUrl || "",
+      debuggerUrl: data.debuggerUrl || existing?.debuggerUrl || "",
+      sessionViewerUrl: existing?.sessionViewerUrl || `${this.config.uiUrl}?sessionId=${data.id}`,
+      timeoutMs: data.timeout || existing?.timeoutMs || 3e5,
+      lastActiveAt: Date.now(),
+      activeController: existing?.activeController ?? (data.status === "live" ? "agent" : "none"),
+      userAgent: data.userAgent
+    };
+    this.activeSessions.set(session.id, session);
+    return session;
+  }
+  /**
+   * Request human takeover for MFA, login, or consent.
+   * Pauses agent automation and sets state to HUMAN_CONTROL.
+   */
+  requestHumanTakeover(sessionId, reason) {
+    const session = this.activeSessions.get(sessionId);
+    if (!session) {
+      throw new Error(`Session ${sessionId} not tracked or already released`);
+    }
+    if (session.state === "RELEASED" || session.state === "EXPIRED" || session.state === "FAILED") {
+      throw new Error(`Cannot initiate takeover on session in state ${session.state}`);
+    }
+    session.state = "HUMAN_CONTROL";
+    session.activeController = "human";
+    session.takeoverReason = reason;
+    session.lastActiveAt = Date.now();
+    const takeoverUrl = `${this.config.uiUrl}?sessionId=${encodeURIComponent(sessionId)}`;
+    const instructions = `[HUMAN TAKEOVER REQUIRED]
+Reason: ${reason}
+Session ID: ${session.id}
+Takeover URL: ${takeoverUrl}
+
+Instructions for Operator:
+1. Open the URL above to access the session UI.
+2. Perform the required authentication / MFA / consent action.
+3. Return to the terminal and signal completion. Automation is paused until you confirm.`;
+    return {
+      session,
+      takeoverUrl,
+      instructions
+    };
+  }
+  /**
+   * Signal that human takeover is complete.
+   * Moves state to VERIFY_AUTHENTICATION before transitioning back to AGENT_CONTROL.
+   */
+  signalHumanComplete(sessionId) {
+    const session = this.activeSessions.get(sessionId);
+    if (!session) {
+      throw new Error(`Session ${sessionId} not tracked or already released`);
+    }
+    if (session.state !== "HUMAN_CONTROL") {
+      throw new Error(`Session ${sessionId} is not in HUMAN_CONTROL state (currently ${session.state})`);
+    }
+    session.state = "VERIFY_AUTHENTICATION";
+    session.activeController = "agent";
+    session.lastActiveAt = Date.now();
+    return {
+      session,
+      state: session.state
+    };
+  }
+  /**
+   * Confirm authentication verification passed and restore AGENT_CONTROL.
+   */
+  confirmAuthenticationVerified(sessionId) {
+    const session = this.activeSessions.get(sessionId);
+    if (!session) {
+      throw new Error(`Session ${sessionId} not tracked or already released`);
+    }
+    if (session.state !== "VERIFY_AUTHENTICATION") {
+      throw new Error(`Session ${sessionId} is not in VERIFY_AUTHENTICATION state (currently ${session.state})`);
+    }
+    session.state = "AGENT_CONTROL";
+    session.activeController = "agent";
+    session.takeoverReason = void 0;
+    session.lastActiveAt = Date.now();
+    return session;
+  }
+  /**
+   * Gracefully release a session.
+   */
+  async releaseSession(sessionId) {
+    try {
+      const res = await fetch(`${this.config.apiUrl}/v1/sessions/${encodeURIComponent(sessionId)}/release`, {
+        method: "POST",
+        headers: this.headers()
+      });
+      const session = this.activeSessions.get(sessionId);
+      if (session) {
+        session.status = "released";
+        session.state = "RELEASED";
+        session.activeController = "none";
+      }
+      this.activeSessions.delete(sessionId);
+      return res.ok;
+    } catch {
+      this.activeSessions.delete(sessionId);
+      return false;
+    }
+  }
+  /**
+   * Perform a direct stateless scrape without manual session management.
+   */
+  async scrape(url) {
+    const res = await fetch(`${this.config.apiUrl}/v1/scrape`, {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify({ url })
+    });
+    if (!res.ok) {
+      const err = await res.text();
+      throw new Error(`Scrape failed (${res.status}): ${err}`);
+    }
+    return res.json();
+  }
+  /**
+   * Perform a direct screenshot action.
+   */
+  async screenshot(url, fullPage = false) {
+    const res = await fetch(`${this.config.apiUrl}/v1/screenshot`, {
+      method: "POST",
+      headers: this.headers(),
+      body: JSON.stringify({ url, fullPage })
+    });
+    if (!res.ok) {
+      const err = await res.text();
+      throw new Error(`Screenshot failed (${res.status}): ${err}`);
+    }
+    return res.json();
+  }
+  /**
+   * Detect and list orphaned or timed-out active sessions.
+   */
+  async checkOrphanedSessions(maxIdleMs = 6e5) {
+    const res = await fetch(`${this.config.apiUrl}/v1/sessions`, {
+      method: "GET",
+      headers: this.headers()
+    });
+    if (!res.ok) {
+      return [];
+    }
+    const data = await res.json();
+    const remoteSessions = data.sessions || [];
+    const now = Date.now();
+    const orphaned = [];
+    for (const rs of remoteSessions) {
+      if (rs.status === "live" || rs.status === "idle") {
+        const tracked = this.activeSessions.get(rs.id);
+        if (!tracked && rs.duration > maxIdleMs) {
+          orphaned.push(rs.id);
+        } else if (tracked && now - tracked.lastActiveAt > maxIdleMs && tracked.state !== "HUMAN_CONTROL") {
+          orphaned.push(rs.id);
+        }
+      }
+    }
+    return orphaned;
+  }
+};
 export {
   BUILTIN_HARNESSES,
   BUILTIN_HARNESS_IDS,
@@ -27642,6 +28188,8 @@ export {
   PI_NATIVE_BRAKE_PROVIDERS,
   PiSession,
   SAFE_HARNESS_COMMAND_ID,
+  SteelClient,
+  VIEWPORT_PRESETS,
   VNEXT_ABSENT_MEMORY_REVISION,
   VNEXT_EVENT_STORE_SCHEMA_VERSION,
   VNEXT_REGISTRY_SCHEMA_VERSION,
@@ -27663,6 +28211,7 @@ export {
   closeVnextRuntimeContext,
   computeGateEvidenceOutcome,
   computeVnextMemoryRevision,
+  createAnnotationFeedback,
   createBackup,
   createLogger,
   createVnextOneShotProducer,
@@ -27677,6 +28226,8 @@ export {
   fileSha256,
   findWinNpmInnerExe,
   foldStoredVnextRun,
+  formatAnnotationFeedbackPrompt,
+  formatCDPEndpoint,
   formatHarnessInventory,
   formatHarnessUpdate,
   formatImprovementReport,
@@ -27721,11 +28272,15 @@ export {
   redactLogValue,
   registerVnextRuntimeCloseHook,
   resolveDispatchStatus,
+  resolvePassCliApiKey,
+  resolveSteelConfig,
+  resolveViewportDimensions,
   restoreBackup,
   restoreDatabaseFile,
   rotateLogFiles,
   runHarnessUpdate,
   runtimeError,
+  sanitizeLogOutput,
   startVnextRuntimeSupervisor,
   tableColumns,
   userTables,