@kontextmind/kxm 0.7.99 → 0.7.101

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.99",
+  "version": "0.7.101",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/skills/kxm-workflow/SKILL.md

@@ -81,10 +81,10 @@ kxm workflow record run_12345 decision "Serialize the fixture setup" --stage-id
 does not read project `.kxm/workflows/*.yaml`; validate those with
 `kxm init --dry-run --json`.
 
-`kxm gate signal` on a KXM run ID (`run_` plus 32 hex digits) goes to the
-Runtime and passes `--recovery-action` through; on a hub webhook run it posts a
-signed callback that needs `KXM_WORKFLOW_ID` and the definition's signal
-secret. Reuse `--delivery-id` to retry one unchanged callback.
+`kxm gate signal` on a run this project's Runtime store holds goes to the
+Runtime and passes `--recovery-action` through; on a hub webhook run, including
+one with the same `run_` + 32-hex shape, it posts a signed callback that needs
+`KXM_WORKFLOW_ID` and the definition's signal secret. Reuse `--delivery-id` to retry one unchanged callback.
 
 ```bash
 kxm gate validate --file workflows.json --json

package/plugins/kxm/src/cli/roles.ts

@@ -19,6 +19,7 @@ import {
 } from "../role.ts";
 import { discoverKxmProjectRoot } from "../project-config.ts";
 import { ensureKxmSupervisor, kxmRuntimeRequest } from "../runtime-supervisor.ts";
+import { projectRuntimeOwnsRun } from "../runtime-store.ts";
 import { resumeWorkflowFromRuling, type WorkflowRun } from "../workflow.ts";
 import { print, printPlan, type CliIo, type Runtime } from "./types.ts";
 
@@ -547,9 +548,9 @@ export async function cmdRoleResume(
 
   const effectiveRuling = ruling?.trim() || "operator_ruling: waived and resumed";
 
-  // Check if it's a KXM run
+  // A run this project's Runtime owns; a hub workflow run of the same id shape falls through.
   const projectRoot = discoverKxmProjectRoot(runtime.cwd);
-  if (projectRoot && /^run_[a-f0-9]{32}$/i.test(runId)) {
+  if (projectRoot && projectRuntimeOwnsRun(projectRoot, runId, runtime.env)) {
     if (runtime.dryRun) {
       printPlan(
         runtime,

package/plugins/kxm/src/cli/workflows.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
+import { stringify } from "yaml";
 import { openReadOnlyDatabase } from "../sqlite.ts";
 import { buildRetrospective, writeRetrospective } from "../retrospective.ts";
 import { redactSecrets } from "../redact.ts";
@@ -10,6 +11,7 @@ import {
   addWorkflowDefinition,
   removeWorkflowDefinition,
   modifyWorkflowDefinition,
+  parseWorkflowFile,
   scaffoldWorkflowDefinition,
   WORKFLOW_TEMPLATES,
 } from "../workflow-manager.ts";
@@ -21,7 +23,7 @@ import {
   type WorkflowJournalEntry,
   type WorkflowRun,
 } from "../workflow.ts";
-import { discoverKxmProjectRoot } from "../project-config.ts";
+import { discoverKxmProjectRoot, kxmWorkflowWriteIssues } from "../project-config.ts";
 import { ensureKxmSupervisor, kxmRuntimeRequest } from "../runtime-supervisor.ts";
 import { projectRuntimeOwnsRun } from "../runtime-store.ts";
 import type { WorkerOutcome } from "../envelope.ts";
@@ -213,12 +215,12 @@ export async function cmdWorkflowAdd(
   },
 ): Promise<number> {
   const scope = options.scope ?? "local";
+  const refuse = (error: string, text: string): number => {
+    print(runtime.io, runtime.json, { ok: false, command: "workflow add", error }, `workflow add failed: ${text}`);
+    return 2;
+  };
   let content: Record<string, unknown> | string | undefined;
   if (options.template !== undefined) {
-    const refuse = (error: string, text: string): number => {
-      print(runtime.io, runtime.json, { ok: false, command: "workflow add", error }, `workflow add failed: ${text}`);
-      return 2;
-    };
     if (options.file !== undefined || options.pick !== undefined) {
       return refuse("workflow_add_conflict", "--template cannot be combined with --file or --pick");
     }
@@ -238,8 +240,10 @@ export async function cmdWorkflowAdd(
     if (scope === "local") {
       const globalDefs = listWorkflowDefinitions({ scope: "global", userConfigDir: runtime.env.KXM_USER_CONFIG_DIR });
       for (const gd of globalDefs) {
-        if (!candidates.some((c) => c.id === gd.id)) {
-          candidates.push({ id: gd.id, description: gd.description, label: "global" });
+        // Read the listed file itself: it may be `.yml`, which a lookup by `<id>.yaml` misses.
+        const definition = parseWorkflowFile(gd.filePath);
+        if (definition && !candidates.some((c) => c.id === gd.id)) {
+          candidates.push({ id: gd.id, description: gd.description, label: "global", payload: definition });
         }
       }
     }
@@ -268,9 +272,30 @@ export async function cmdWorkflowAdd(
   }
 
   try {
-    const res = addWorkflowDefinition(workflowId!, content, {
+    const document = typeof content === "string" ? content : stringify(content);
+    // A local workflow is read by the project loader, which refuses the whole
+    // project over one bad file, so it is checked by that loader before it lands.
+    let repoRoot = runtime.cwd;
+    if (scope === "local") {
+      const projectRoot = discoverKxmProjectRoot(runtime.cwd);
+      if (!projectRoot) {
+        return refuse("project_not_found", "local workflows belong to a KXM project; run kxm init at the repository root, or pass --scope global");
+      }
+      const issues = kxmWorkflowWriteIssues(projectRoot, workflowId!, document);
+      if (issues.length > 0) {
+        print(
+          runtime.io,
+          runtime.json,
+          { ok: false, command: "workflow add", error: "workflow_invalid", issues },
+          `workflow add failed: with this workflow the project would not load, so nothing was written\n${issues.map((entry) => `  ${entry.file}: ${entry.code}: ${entry.message}`).join("\n")}`,
+        );
+        return 2;
+      }
+      repoRoot = projectRoot;
+    }
+    const res = addWorkflowDefinition(workflowId!, document, {
       scope,
-      repoRoot: runtime.cwd,
+      repoRoot,
       userConfigDir: runtime.env.KXM_USER_CONFIG_DIR,
       overwrite: options.overwrite,
       dryRun: runtime.dryRun,

package/plugins/kxm/src/mcp-server.ts

@@ -11,7 +11,7 @@ import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 import { sessionTokenFixHint } from "./session-token-hint.ts";
 
-const VERSION = "0.7.99";
+const VERSION = "0.7.101";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();

package/plugins/kxm/src/project-config.ts

@@ -453,10 +453,14 @@ function readResource(
     parent = dirname(parent);
   }
   if (!stat.isFile()) fail("path", "resource_not_file", label, "configuration resource must be a regular file");
-  const value = parseRestrictedYaml(readFileSync(file), label);
+  return { kind, ...(id === undefined ? {} : { id }), file, logicalPath, value: resourceValue(registry, readFileSync(file), label, kind) };
+}
+
+function resourceValue(registry: KxmSchemaRegistry, input: string | Uint8Array, label: string, kind: KxmResourceKind): JsonObject {
+  const value = parseRestrictedYaml(input, label);
   const issues = registry.validate(kind, value, label);
   if (issues.length > 0) throw new KxmConfigError(issues);
-  return { kind, ...(id === undefined ? {} : { id }), file, logicalPath, value };
+  return value;
 }
 
 function readTemplateProvenance(registry: KxmSchemaRegistry, root: string): JsonObject | undefined {
@@ -513,6 +517,7 @@ function listNamedResources(
   directory: string,
   logicalDirectory: string,
   kind: "agent" | "model" | "workflow",
+  replacedId?: string,
 ): Map<string, KxmResource> {
   const resources = new Map<string, KxmResource>();
   if (!existsSync(directory)) return resources;
@@ -534,6 +539,7 @@ function listNamedResources(
     }
     const id = basename(entry.name, ".yaml");
     if (kind === "model" && id === "inventory") continue;
+    if (id === replacedId) continue;
     if (!resourceIdentifier(id)) {
       issues.push(issue("path", "resource_id_invalid", displayPath(root, join(directory, entry.name)), `filename-derived identity ${id} is invalid or platform-reserved`));
       continue;
@@ -1284,6 +1290,34 @@ export function assertNoRegisteredGates(options: object): void {
 
 /** Load and semantically validate one complete, path-derived KXM configuration bundle. */
 export function loadKxmProject(projectRoot: string, options: KxmConfigOptions = {}): KxmProjectBundle {
+  return loadProjectBundle(projectRoot, options);
+}
+
+/**
+ * What `loadKxmProject` would refuse once `.kxm/workflows/<workflowId>.yaml` held
+ * `document`, found without writing it: the same parser, schema and bundle rules,
+ * with `document` standing in for any file of that name.
+ */
+export function kxmWorkflowWriteIssues(
+  projectRoot: string,
+  workflowId: string,
+  document: string,
+  options: KxmConfigOptions = {},
+): readonly KxmConfigIssue[] {
+  try {
+    loadProjectBundle(projectRoot, options, { id: workflowId, document });
+    return [];
+  } catch (error) {
+    if (error instanceof KxmConfigError) return error.issues;
+    throw error;
+  }
+}
+
+function loadProjectBundle(
+  projectRoot: string,
+  options: KxmConfigOptions,
+  workflowCandidate?: { id: string; document: string },
+): KxmProjectBundle {
   assertNoRegisteredGates(options);
   const root = resolve(projectRoot);
   const legacyPresent = legacyConfigFilesAt(root);
@@ -1323,7 +1357,15 @@ export function loadKxmProject(projectRoot: string, options: KxmConfigOptions =
 
   const agents = listNamedResources(registry, root, join(root, ".kxm", "agents"), ".kxm/agents", "agent");
   const models = listNamedResources(registry, root, join(root, ".kxm", "models"), ".kxm/models", "model");
-  const workflows = listNamedResources(registry, root, join(root, ".kxm", "workflows"), ".kxm/workflows", "workflow");
+  const workflows = listNamedResources(registry, root, join(root, ".kxm", "workflows"), ".kxm/workflows", "workflow", workflowCandidate?.id);
+  if (workflowCandidate) {
+    const { id, document } = workflowCandidate;
+    const logicalPath = `.kxm/workflows/${id}.yaml`;
+    if (!resourceIdentifier(id)) fail("path", "resource_id_invalid", logicalPath, `filename-derived identity ${id} is invalid or platform-reserved`);
+    const collision = [...workflows.keys()].find((candidate) => candidate.toLocaleLowerCase("en-US") === id.toLocaleLowerCase("en-US"));
+    if (collision) fail("path", "resource_id_collision", logicalPath, `${id} case-folds to existing ${collision}`);
+    workflows.set(id, { kind: "workflow", id, file: join(root, logicalPath), logicalPath, value: resourceValue(registry, document, logicalPath, "workflow") });
+  }
   const gatePath = join(root, ".kxm", "gates.yaml");
   const gateRegistry = existsSync(gatePath) ? readResource(registry, root, gatePath, ".kxm/gates.yaml", "gate-registry") : undefined;
   const environments: KxmResource[] = [];

package/plugins/kxm/src/runtime-store.ts

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
-import { DatabaseSync } from "./sqlite.ts";
+import { DatabaseSync, openReadOnlyDatabase } from "./sqlite.ts";
 import { KxmConfigError, validateCoordinator, validateDriveReceipt, validateIntakeMessage, validateRunEvent, kxmCanonicalJson, type JsonValue, type KxmConfigIssue, type KxmConfigOptions } from "./project-config.ts";
 import { kxmUserStateRoot } from "./bindings.ts";
 import { deriveKxmSyncEvent, kxmSyncEventBytes, KxmSyncRedactor } from "./sync-transform.ts";
@@ -59,13 +59,13 @@ export function kxmProjectRunEventsPath(projectRoot: string, env: NodeJS.Process
 /**
  * Whether this project's Runtime event store holds `runId`. Hub workflow runs and Runtime
  * runs share the `run_<32 hex>` shape, so a command addressed by run id asks the owning
- * store instead of guessing from the id. Read-only; a project whose Runtime never ran
- * owns no runs.
+ * store instead of guessing from the id. Read-only and leaves no sidecars, so a dry run
+ * can ask; a project whose Runtime never ran owns no runs.
  */
 export function projectRuntimeOwnsRun(projectRoot: string, runId: string, env: NodeJS.ProcessEnv): boolean {
   const path = kxmProjectRunEventsPath(projectRoot, env);
   if (!existsSync(path)) return false;
-  const database = new DatabaseSync(path, { readOnly: true });
+  const database = openReadOnlyDatabase(path);
   try {
     database.exec("PRAGMA busy_timeout = 5000");
     return database.prepare("SELECT 1 FROM runs WHERE run_id = ?").get(runId) !== undefined;