@kontextmind/kxm 0.7.0 → 0.7.5

package/plugins/kxm/dist/server.js

@@ -7431,6 +7431,61 @@ function parseBoundedInteger(value, field, fallback, min, max) {
   }
   return value;
 }
+var TERMINAL_RECEIPT_SCHEMA = "kxm.terminal-receipt.v1";
+var VALID_TERMINAL_STATUSES = /* @__PURE__ */ new Set(["accepted", "audit_escalation", "rejected", "error"]);
+function validateTerminalReceipt(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new ProtocolError(400, "terminal receipt must be an object", "invalid_terminal_receipt");
+  }
+  const record = value;
+  if (record.schema !== void 0 && record.schema !== TERMINAL_RECEIPT_SCHEMA) {
+    throw new ProtocolError(400, `terminal receipt schema must be ${TERMINAL_RECEIPT_SCHEMA}`, "invalid_terminal_receipt");
+  }
+  const status = record.status;
+  if (!status || !VALID_TERMINAL_STATUSES.has(status)) {
+    throw new ProtocolError(
+      400,
+      `terminal receipt status must be one of: ${Array.from(VALID_TERMINAL_STATUSES).join(", ")}`,
+      "invalid_terminal_receipt"
+    );
+  }
+  const seat = requireString(record.seat, "seat", { max: 64 });
+  const runId = requireString(record.runId, "runId", { max: 128 });
+  const stageId = requireString(record.stageId, "stageId", { max: 128 });
+  const timestamp = requireString(record.timestamp, "timestamp", { max: 64 });
+  const host2 = requireString(record.host, "host", { max: 64 });
+  const model = requireString(record.model, "model", { max: 128 });
+  let evidence;
+  if (record.evidence !== void 0) {
+    if (!record.evidence || typeof record.evidence !== "object" || Array.isArray(record.evidence)) {
+      throw new ProtocolError(400, "terminal receipt evidence must be an object", "invalid_terminal_receipt");
+    }
+    evidence = record.evidence;
+  }
+  let metrics;
+  if (record.metrics !== void 0) {
+    if (!record.metrics || typeof record.metrics !== "object" || Array.isArray(record.metrics)) {
+      throw new ProtocolError(400, "terminal receipt metrics must be an object", "invalid_terminal_receipt");
+    }
+    metrics = record.metrics;
+  }
+  const escalationReason = optionalString(record.escalationReason, "escalationReason", 1024);
+  const ruling = optionalString(record.ruling, "ruling", 2048);
+  return {
+    schema: TERMINAL_RECEIPT_SCHEMA,
+    status,
+    seat,
+    runId,
+    stageId,
+    timestamp,
+    host: host2,
+    model,
+    ...evidence ? { evidence } : {},
+    ...metrics ? { metrics } : {},
+    ...escalationReason ? { escalationReason } : {},
+    ...ruling ? { ruling } : {}
+  };
+}
 
 // plugins/kxm/src/diagnostics.ts
 function workflowScopeExtras(operation, assignedCoordinatorName) {
@@ -7982,12 +8037,17 @@ function parseWorkflowDefinitions(raw, environment = process.env, onWarning) {
       if (stageMaxTransitions !== void 0 && (!Number.isInteger(stageMaxTransitions) || stageMaxTransitions < 1 || stageMaxTransitions > 100)) {
         throw new Error(`stage ${stageId} maxTransitions must be an integer between 1 and 100`);
       }
+      const autoResumeLimit = stage.autoResumeLimit;
+      if (autoResumeLimit !== void 0 && (!Number.isInteger(autoResumeLimit) || autoResumeLimit < 1 || autoResumeLimit > 20)) {
+        throw new Error(`stage ${stageId} autoResumeLimit must be an integer between 1 and 20`);
+      }
       return {
         id: stageId,
         label: requireString(stage.label ?? stageId, "stage.label", { max: 128 }),
         instructions: requireString(stage.instructions, "stage.instructions", { max: 4e3 }),
         requiredEvidence,
         maxAttempts,
+        ...autoResumeLimit !== void 0 ? { autoResumeLimit } : {},
         ...area ? { area } : {},
         ...evidencePolicies ? { evidencePolicies } : {},
         ...on ? { on } : {},
@@ -8266,6 +8326,31 @@ function checkpointRun(run, stageId, status, summary, evidence, timestamp, verif
       delete run.currentStage;
       return { retry: false, completed: false, run };
     }
+    if (stage.autoResumeLimit !== void 0 && stage.attempts >= stage.autoResumeLimit) {
+      stage.status = "in_progress";
+      const reason = summary || `autoResumeLimit of ${stage.autoResumeLimit} reached on stage ${stage.id}`;
+      const receipt = validateTerminalReceipt({
+        schema: TERMINAL_RECEIPT_SCHEMA,
+        status: "audit_escalation",
+        seat: stage.id,
+        runId: run.id,
+        stageId: stage.id,
+        timestamp,
+        host: "pi",
+        model: "default",
+        escalationReason: reason
+      });
+      const expiresAt = new Date(Date.parse(timestamp) + 24 * 60 * 60 * 1e3).toISOString();
+      waitForWorkflowSignal(run, stage.id, "audit_escalation", reason, timestamp, expiresAt);
+      stage.receipt = receipt;
+      stage.auditEscalation = {
+        reason,
+        timestamp,
+        receipt
+      };
+      return { retry: false, completed: false, run };
+    }
+    stage.status = status;
     const outcomeKey = outcome ?? status;
     const rule = resolveOutcomeRule(stage, outcomeKey);
     if (rule && stage.attempts < stage.maxAttempts) {
@@ -10833,7 +10918,45 @@ import {
   writeFileSync as writeFileSync4
 } from "node:fs";
 import { basename as basename3, dirname as dirname3, join as join4, resolve as resolve4 } from "node:path";
-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-config.ts
 import { basename as basename2, dirname as dirname2, extname as extname2, isAbsolute, join as join3, relative, resolve as resolve3, sep } from "node:path";
@@ -11090,7 +11213,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;
@@ -11144,7 +11269,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
@@ -11207,7 +11332,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

package/plugins/kxm/dist/vnext-runtime-supervisor.js

@@ -15126,6 +15126,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") });
@@ -15162,11 +15175,7 @@ function defaultSpawn(command, args, options) {
       resolve7({ 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;
@@ -15493,7 +15502,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;
@@ -15547,7 +15558,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
@@ -15610,7 +15621,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
@@ -16905,7 +16916,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();
@@ -16973,6 +16984,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) {
@@ -17153,7 +17191,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 {
@@ -17265,7 +17303,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";
@@ -17308,7 +17386,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]);
@@ -17388,7 +17465,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}`);
@@ -22465,6 +22542,32 @@ function evaluateArtifactsGate(context, definition) {
 // plugins/kxm/src/vnext-engine-command.ts
 import { spawn as spawn2 } from "node:child_process";
 import { createHash as createHash8 } 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;
@@ -22581,6 +22684,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 {
@@ -23706,6 +23810,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,
@@ -25483,6 +25588,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`);
     }

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kxm-claude-plugin",
-  "version": "0.7.0",
+  "version": "0.7.5",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/skills/hints.json

@@ -68,6 +68,36 @@
       "argumentHint": "[trailers|trust|gates|authz|webhooks]",
       "triggers": ["KM-Session", "trust mode", "secret gate", "RLS", "protocol"],
       "complete": ["trailers", "trust", "gates", "authz", "webhooks"]
+    },
+    {
+      "name": "kxm-browser-session",
+      "argumentHint": "[create|inspect|release|cdp]",
+      "triggers": ["browser session", "steel session", "remote browser", "launch browser", "cdp endpoint"],
+      "complete": ["create session", "inspect session", "release session", "format cdp"]
+    },
+    {
+      "name": "kxm-browser-takeover",
+      "argumentHint": "[request|signal|verify]",
+      "triggers": ["human takeover", "mfa login", "takeover url", "browser auth required", "resume browser"],
+      "complete": ["request takeover", "signal complete", "verify auth"]
+    },
+    {
+      "name": "kxm-browser-explore",
+      "argumentHint": "[open|snapshot|get|screenshot]",
+      "triggers": ["agent-browser", "explore web", "scrape page", "dom snapshot"],
+      "complete": ["agent-browser open", "agent-browser snapshot", "agent-browser get", "agent-browser screenshot"]
+    },
+    {
+      "name": "kxm-browser-verify",
+      "argumentHint": "[reproduce|test|assert|trace]",
+      "triggers": ["playwright test", "ui reproduction", "regression test", "e2e verify"],
+      "complete": ["playwright test", "reproduce issue", "save trace"]
+    },
+    {
+      "name": "kxm-browser-diagnostics",
+      "argumentHint": "[check|cleanup|recover]",
+      "triggers": ["browser diagnostics", "cdp failure", "session timeout", "orphaned browser"],
+      "complete": ["check health", "cleanup orphans", "recover session"]
     }
   ]
 }

package/plugins/kxm/skills/kxm-browser-annotate/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: kxm-browser-annotate
+description: Capture a visual DOM section or element, attach structured annotations and change requests, and send them back to the agent.
+---
+
+# KXM Browser Section Capture & Visual Annotation Feedback
+
+Use this skill to capture visual screenshots of specific UI sections or elements from a Steel browser session, record structured design/code annotations, and feed actionable change requests directly back to an AI coding agent.
+
+## Purpose & Scope
+
+- Enable human operators and critic agents to visually review web interfaces.
+- Crop or capture specific DOM elements, cards, modals, or viewport bounding boxes.
+- Attach structured notes (e.g. alignment issues, color contrast, missing data, layout bugs) with severity ratings.
+- Provide a standardized Markdown/JSON feedback payload that an agent can parse and implement immediately.
+
+## Workflow
+
+```text
+1. CAPTURE SECTION
+   └─ Use Playwright element.screenshot() or agent-browser screenshot to isolate the target component.
+
+2. ATTACH ANNOTATIONS
+   └─ Record bounding box / element selector, defect note, and severity rating.
+
+3. ASSEMBLE FEEDBACK PACKAGE
+   └─ Package screenshot artifact, element selectors, notes, and concrete change list.
+
+4. HANDOFF TO AGENT
+   └─ Inject formatted visual feedback into agent context or KXM workflow run.
+
+5. AGENT IMPLEMENTS FIX
+   └─ Agent modifies code, re-captures the section, and verifies the change visually and with Playwright.
+```
+
+## Capturing a Specific Section with Playwright
+
+```typescript
+import { chromium } from "playwright";
+import { resolveSteelConfig, formatCDPEndpoint } from "@kontextmind/kxm/runtime";
+
+async function captureSection(sessionId: string, selector: string, outputPath: string) {
+  const config = resolveSteelConfig();
+  const cdpUrl = formatCDPEndpoint({ id: sessionId, websocketUrl: "" }, config);
+
+  const browser = await chromium.connectOverCDP(cdpUrl);
+  const context = browser.contexts()[0] || await browser.newContext();
+  const page = context.pages()[0] || await context.newPage();
+
+  const element = page.locator(selector);
+  await element.screenshot({ path: outputPath });
+
+  await browser.close();
+}
+```
+
+## Structured Feedback Schema
+
+```json
+{
+  "sessionId": "sess_12345",
+  "url": "https://app.example.com/settings/billing",
+  "sectionSelector": "[data-testid='subscription-card']",
+  "screenshotPath": ".kxm/artifacts/browser/billing-card.png",
+  "overallSummary": "Pricing tier badge overflows card boundary on narrow screens",
+  "annotations": [
+    {
+      "label": "Badge Overflow",
+      "selector": ".badge-tier",
+      "note": "Text overflows container when tier name is 'Enterprise Plus'",
+      "severity": "fix"
+    },
+    {
+      "label": "Button Padding",
+      "selector": "button.upgrade-btn",
+      "note": "Increase vertical padding from 8px to 12px for touch target compliance",
+      "severity": "suggestion"
+    }
+  ],
+  "requestedChanges": [
+    "Add `overflow: hidden` or `flex-wrap: wrap` to the subscription header container",
+    "Update `.badge-tier` CSS to support dynamic text wrapping",
+    "Adjust `button.upgrade-btn` padding to `py-3 px-4`"
+  ]
+}
+```
+
+## Formatting for the Agent
+
+Use `formatAnnotationFeedbackPrompt()` from `@kontextmind/kxm/runtime` to render a clean, checklist-driven prompt that the agent executes step-by-step.

package/plugins/kxm/skills/kxm-browser-auth/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: kxm-browser-auth
+description: Retrieve application credentials and manage authenticated browser profiles safely via pass-cli without secret exposure.
+---
+
+# KXM Browser Credentials & Authenticated Profiles
+
+Use this skill to retrieve target application credentials and manage browser session state securely using `pass-cli` as the sole authoritative store.
+
+## Purpose & Scope
+
+- Enforce `pass-cli` as the single source of truth for credentials and API keys.
+- Prevent secrets from leaking into git repositories, logs, prompts, or model-visible tool outputs.
+- Support safe storage and retrieval of session storage state and authenticated profiles.
+
+## Credential Retrieval Guidelines
+
+### 1. Authoritative Tool: pass-cli
+
+Always retrieve credentials and API keys directly from `pass-cli`:
+
+```bash
+# Retrieve target login password into an environment variable or piping mechanism
+pass-cli item view --vault-name "<vault>" --item-title "<title>" --field password
+
+# Retrieve Steel infrastructure API key
+pass-cli item view --vault-name "AI Provider Keys" --item-title "Steel Browser (KontextMind DOKS)" --field STEEL_API_KEY
+```
+
+### 2. Secret Redaction Invariants
+
+- **Never** write plain passwords, session tokens, or API keys into markdown docs, commit messages, or prompts.
+- **Never** pass plain credentials as unredacted command line arguments in shared logs.
+- Use environment variable injection (`pass-cli run`) or direct in-memory pipes.
+
+### 3. Profile & Storage State Management
+
+When an authenticated session state (cookies, local storage) needs to be preserved for subsequent test runs:
+
+1. **Extract State**:
+   Extract storage state from Playwright via `context.storageState({ path: 'state.json' })` or from Steel via `GET /v1/sessions/:id/context`.
+2. **Encrypt / Store Privately**:
+   Store sensitive storage state in git-ignored, private locations (e.g. `.kxm/state/browser/` or as an encrypted secret).
+3. **Session Expiration**:
+   Treat cookies as transient. When expired, trigger the `kxm-browser-takeover` flow instead of failing silently.
+4. **Account & Profile Separation**:
+   Maintain separate storage states per environment (e.g., `dev`, `staging`, `prod`) and per user role (e.g., `admin`, `viewer`). Never mix profiles across concurrent test runs.

package/plugins/kxm/skills/kxm-browser-diagnostics/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: kxm-browser-diagnostics
+description: Diagnose and recover from Steel connectivity failures, CDP attachment issues, session timeouts, and orphaned browsers.
+---
+
+# KXM Browser Diagnostics and Recovery
+
+Use this skill to investigate and resolve connectivity failures, CDP attachment errors, session timeouts, profile contention, and orphaned browser resources.
+
+## Common Failure Modes & Resolutions
+
+### 1. Steel API Connectivity / 401 Unauthorized
+
+- **Symptom**: `Failed to fetch Steel session (401)` or `Connection refused`.
+- **Diagnosis**:
+  - Verify Steel API endpoint is reachable: `curl -sI https://steel.kontextmind.com/v1/health`.
+  - Check `STEEL_API_KEY` in `pass-cli`: `pass-cli item view --vault-name "AI Provider Keys" --item-title "Steel Browser (KontextMind DOKS)"`.
+- **Remedy**: Update expired or missing API key in your session environment.
+
+### 2. CDP WebSocket Attachment Failure
+
+- **Symptom**: `WebSocket connection to wss://... failed: 404/500`.
+- **Diagnosis**:
+  - Check if the target session ID has already been released or timed out.
+  - Verify ingress WebSocket headers: ensure `nginx.ingress.kubernetes.io/websocket-services` is enabled.
+- **Remedy**: Query `GET /v1/sessions/<id>`. If status is `released`, launch a fresh session.
+
+### 3. Session Timeout & Expiration
+
+- **Symptom**: Session drops abruptly during human takeover or long idling.
+- **Diagnosis**: Steel enforces a default session timeout (300s–1800s).
+- **Remedy**:
+  - If a long human task is required, set a higher initial `timeout` parameter during session creation (e.g. `1800000` ms for 30 minutes).
+  - On expiration, do not claim continuity: inform the operator and launch a clean session.
+
+### 4. Interactive Takeover Viewer Inaccessible
+
+- **Symptom**: `https://steel.kontextmind.com/ui` opens but cannot interact with elements.
+- **Diagnosis**: Self-hosted Steel OSS serves the session screencast and devtools.
+- **Remedy**: Connect directly to the devtools inspector URL: `https://steel.kontextmind.com/v1/devtools/inspector.html` or open the browser devtools panel to perform input actions.
+
+### 5. Orphaned Browser Processes & Cleanup
+
+- **Symptom**: Node memory pressure or high active session counts.
+- **Diagnosis**: Query active sessions list: `curl -s https://steel.kontextmind.com/v1/sessions`.
+- **Remedy**:
+  - Iterate through inactive sessions and post `/release` for each stale ID.
+  - Ensure all automation scripts wrap browser usage in `try...finally` to release sessions reliably.