@kontextmind/kxm 0.7.167 → 0.7.169

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

@@ -17261,7 +17261,28 @@ var RESOURCE_SCHEMA = Object.freeze({
 var IDENTIFIER2 = /^[a-z][a-z0-9]*(?:[-_][a-z0-9]+)*$/;
 var WINDOWS_RESERVED = /^(?:con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³]|conin\$|conout\$|clock\$)$/i;
 var BUILTIN_EXECUTORS = ["local", "ssh", "exe-dev"];
-var BUILTIN_TOOL_PRESETS = ["coordinator", "read-only", "workspace-writer", "tests-writer"];
+var TOOL_PRESET_PROFILES = Object.freeze({
+  coordinator: "read-only",
+  "read-only": "read-only",
+  "workspace-writer": "edit",
+  "tests-writer": "edit"
+});
+var BUILTIN_TOOL_PRESETS = Object.keys(TOOL_PRESET_PROFILES);
+function toolPresetProfile(preset) {
+  if (!Object.hasOwn(TOOL_PRESET_PROFILES, preset)) return void 0;
+  return TOOL_PRESET_PROFILES[preset];
+}
+function toolPresetExceedsRoleMessage(preset, roleId, rolePermission, rolePreset) {
+  const profile = toolPresetProfile(preset);
+  if (profile !== "edit") return void 0;
+  if (rolePermission === "read-only") {
+    return `tools.preset ${preset} exceeds role ${roleId} permission read-only`;
+  }
+  if (rolePreset !== void 0 && toolPresetProfile(rolePreset) === "read-only") {
+    return `tools.preset ${preset} exceeds role ${roleId} preset ${rolePreset}`;
+  }
+  return void 0;
+}
 var SECRET_VALUE_PATTERNS = [
   /-----BEGIN (?:[A-Z ]+ )?PRIVATE KEY-----/,
   /\b(?:ghp|github_pat)_[A-Za-z0-9_]{20,}\b/,
@@ -17661,6 +17682,15 @@ function objectValue(value) {
 function stringValue(value) {
   return typeof value === "string" ? value : void 0;
 }
+function roleById(roles, roleId) {
+  const direct = roles.get(roleId);
+  if (direct) return direct;
+  const folded = roleId.toLocaleLowerCase("en-US");
+  for (const role of roles.values()) {
+    if ((role.id ?? "").toLocaleLowerCase("en-US") === folded) return role;
+  }
+  return void 0;
+}
 function numberValue(value, fallback) {
   return typeof value === "number" ? value : fallback;
 }
@@ -18175,10 +18205,29 @@ function validateBundle(project, repositories, agents, models, workflows, enviro
     if (executor && !executors.has(executor)) issues.push(issue3("reference", "executor_unknown", agent.logicalPath, `executor ${executor} is not registered`));
     const preset = stringValue(objectValue(agent.value.tools)?.preset);
     if (preset && !presets.has(preset)) issues.push(issue3("reference", "tool_preset_unknown", agent.logicalPath, `tool preset ${preset} is not registered`));
+    const roleId = stringValue(agent.value.role);
+    const role = roleId ? roleById(roles, roleId) : void 0;
+    const rolePermission = stringValue(role?.value.permission);
+    if (preset && role && (rolePermission === "edit" || rolePermission === "read-only")) {
+      const message = toolPresetExceedsRoleMessage(
+        preset,
+        role.id ?? roleId ?? "role",
+        rolePermission,
+        stringValue(objectValue(role.value.tools)?.preset)
+      );
+      if (message) issues.push(issue3("semantic", "tool_preset_exceeds_role", agent.logicalPath, message));
+    }
     for (const repositoryId of Object.keys(objectValue(agent.value.repositories) ?? {})) {
       if (!repositoryIds.has(repositoryId)) issues.push(issue3("reference", "repository_unknown", agent.logicalPath, `references unknown repository ${repositoryId}`));
     }
   }
+  for (const role of roles.values()) {
+    const permission = stringValue(role.value.permission);
+    const rolePreset = stringValue(objectValue(role.value.tools)?.preset);
+    if (permission === "read-only" && rolePreset && toolPresetProfile(rolePreset) === "edit") {
+      issues.push(issue3("semantic", "tool_preset_exceeds_role", role.logicalPath, `tools.preset ${rolePreset} exceeds permission read-only`));
+    }
+  }
   validateModelReferences(models, issues);
   const defaultWorkflow = stringValue(project.value.defaultWorkflow) ?? "default";
   if (!lookupKxmResource(workflows.values(), defaultWorkflow, "workflow")) issues.push(issue3("reference", "default_workflow_unknown", project.logicalPath, `default workflow ${defaultWorkflow} does not exist`));
@@ -29377,6 +29426,68 @@ function unsupportedAgentStepTimeout(step, limitMs) {
     detail: "step timeoutMs is wider than project limits.agentStepTimeoutMs"
   };
 }
+function narrowerPermission(left, right) {
+  return left === "read-only" || right === "read-only" ? "read-only" : "edit";
+}
+function stepRepositoryPermission(step) {
+  return Object.values(step.repositories).some((access) => access === "write") ? "edit" : "read-only";
+}
+function stepAccessDetail(step) {
+  const entries = Object.entries(step.repositories);
+  if (entries.length === 0) return "none";
+  return entries.map(([id, access]) => `${id} ${access}`).sort((left, right) => left < right ? -1 : left > right ? 1 : 0).join(", ");
+}
+function yamlToolsPreset(doc) {
+  const tools = doc?.tools;
+  if (!tools || typeof tools !== "object" || Array.isArray(tools)) return void 0;
+  const preset = tools.preset;
+  return typeof preset === "string" && preset.length > 0 ? preset : void 0;
+}
+function resolveToolDispatch(projectRoot, step, agentId) {
+  const stepPermission = stepRepositoryPermission(step);
+  if (step.kind !== "agent" && step.kind !== "moa") return { permission: stepPermission };
+  const agentFile = findYamlBasename(join18(projectRoot, ".kxm", "agents"), agentId, "agent") ?? agentId;
+  const agent = readYamlFile(join18(projectRoot, ".kxm", "agents", `${agentFile}.yaml`));
+  const roleId = typeof agent?.role === "string" ? agent.role : "";
+  if (!roleId) return { permission: stepPermission };
+  const roleDoc = readYamlFile(join18(projectRoot, ".kxm", "roles", `${roleId}.yaml`));
+  const rawPermission = roleDoc?.permission;
+  const rolePermission = rawPermission === "edit" || rawPermission === "read-only" ? rawPermission : void 0;
+  if (!rolePermission) return { permission: stepPermission };
+  const rolePreset = yamlToolsPreset(roleDoc);
+  const agentPreset = yamlToolsPreset(agent);
+  const rolePresetProfile = rolePreset ? toolPresetProfile(rolePreset) : void 0;
+  if (rolePreset && rolePresetProfile === "edit" && rolePermission === "read-only") {
+    return {
+      error: {
+        reason: "step_unsupported",
+        field: "tools.preset",
+        detail: `tools.preset ${rolePreset} exceeds role ${roleId} permission read-only`
+      }
+    };
+  }
+  if (agentPreset) {
+    const exceeds = toolPresetExceedsRoleMessage(agentPreset, roleId, rolePermission, rolePreset);
+    if (exceeds) {
+      return { error: { reason: "step_unsupported", field: "tools.preset", detail: exceeds } };
+    }
+  }
+  let chain = rolePermission;
+  if (rolePresetProfile) chain = narrowerPermission(chain, rolePresetProfile);
+  const agentProfile = agentPreset ? toolPresetProfile(agentPreset) : void 0;
+  if (agentProfile) chain = narrowerPermission(chain, agentProfile);
+  const permission = narrowerPermission(chain, stepPermission);
+  if (stepPermission === "edit" && permission === "read-only") {
+    return {
+      error: {
+        reason: "step_unsupported",
+        field: "permission",
+        detail: `role permission ${rolePermission} resolves to ${chain}; step access ${stepAccessDetail(step)}`
+      }
+    };
+  }
+  return { permission };
+}
 function executingSingletonAttempt(plan, state) {
   const current = state.currentStep;
   if (!current || current.panel.order.length !== 1) return void 0;
@@ -29569,10 +29680,17 @@ function prepareDispatch(context, runId, producerId, dispatchSources) {
   if (unsupported) return { kind: "return", state, handoff: { ...unsupported, stepId } };
   const wideTimeout = unsupportedAgentStepTimeout(step, projectAgentStepTimeoutMs(context, run));
   if (wideTimeout) return { kind: "return", state, handoff: { ...wideTimeout, stepId } };
+  const firstListed = step.assignments.allowedAgents[0];
+  const firstAgentId = step.kind === "agent" || step.kind === "moa" ? firstListed ? firstListed : step.agent : void 0;
+  if (firstAgentId) {
+    const toolDispatch = resolveToolDispatch(context.projectRoot, step, firstAgentId);
+    if ("error" in toolDispatch) {
+      return { kind: "return", state, handoff: { ...toolDispatch.error, stepId } };
+    }
+  }
   let resolvedRoute;
   if (producerId !== "driver-simulated") {
-    const allowed = step.assignments.allowedAgents;
-    const agentId = allowed && allowed.length > 0 && allowed[0] ? allowed[0] : step.kind === "agent" || step.kind === "moa" ? step.agent : "coordinator";
+    const agentId = firstAgentId ?? (step.kind === "agent" || step.kind === "moa" ? step.agent : "coordinator");
     const routeResult = resolveProducerRoute(context.projectRoot, step, agentId);
     if ("error" in routeResult) {
       return { kind: "return", state, handoff: { ...routeResult.error, stepId } };
@@ -29692,6 +29810,10 @@ function birthMember(context, input) {
   const born = folded.currentStep?.panel.order.length ?? 0;
   const allowed = input.step.assignments.allowedAgents;
   const agentId = allowed && allowed.length > born && allowed[born] ? allowed[born] : input.step.kind === "agent" || input.step.kind === "moa" ? input.step.agent : "coordinator";
+  const toolDispatch = resolveToolDispatch(context.projectRoot, input.step, agentId);
+  if ("error" in toolDispatch) {
+    return { handoff: { ...toolDispatch.error, stepId: input.stepId } };
+  }
   let resolvedRoute = input.resolvedRoute;
   if (!resolvedRoute && input.producerId && input.producerId !== "driver-simulated") {
     const routeResult = resolveProducerRoute(context.projectRoot, input.step, agentId);
@@ -29781,7 +29903,7 @@ function birthMember(context, input) {
       stepAttempt: input.stepAttempt,
       objective: promptText,
       allowedOutcomes: [...input.step.outcomes],
-      permissionCeiling: Object.values(input.step.repositories).some((access) => access === "write") ? "edit" : "read-only"
+      permissionCeiling: toolDispatch.permission
     },
     acceptanceCriteria: input.step.requiredEvidence.map((ev) => ({
       id: ev.key,
@@ -29826,7 +29948,7 @@ function birthMember(context, input) {
       prompt: input.step.instructions ? `${input.step.instructions}
 
 ${generatedPrompt}` : generatedPrompt,
-      permission: Object.values(input.step.repositories).some((access) => access === "write") ? "edit" : "read-only",
+      permission: toolDispatch.permission,
       ...(input.step.kind === "agent" || input.step.kind === "moa") && input.step.timeoutMs !== void 0 ? { timeoutMs: input.step.timeoutMs } : {},
       contextPacket,
       ...resolvedRoute?.effort !== void 0 ? { thinking: resolvedRoute.effort } : {},
@@ -31668,6 +31790,9 @@ function resolveUserStateRoot(env) {
 function hubBindingFile(env = process.env) {
   return join19(resolveUserStateRoot(env), "hub-binding.json");
 }
+function hubBindingCloudFile(env = process.env) {
+  return join19(resolveUserStateRoot(env), "hub-binding.cloud.json");
+}
 function validateHubUrl(raw) {
   let parsed;
   try {
@@ -31777,33 +31902,37 @@ function isIsoTimestamp(value) {
   if (Number.isNaN(Date.parse(value))) return false;
   return value === new Date(value).toISOString();
 }
-function readHubBinding(env = process.env) {
-  const file = hubBindingFile(env);
-  if (!existsSync16(file)) return void 0;
+var LEGACY_BINDING_KEYS = ["schema", "url", "boundAt"];
+var BINDING_KEYS = /* @__PURE__ */ new Set([...LEGACY_BINDING_KEYS, "cloud", "tokenEnv", "tokenCommand"]);
+function bindingFallbackWarning(file, reason) {
+  return `hub binding at ${file} ${reason}; falling back to the local hub. Restart the Runtime supervisor, the hub, and workers after upgrading and before a cloud bind.`;
+}
+function writeBindingJson(file, value) {
+  mkdirSync7(dirname9(file), { recursive: true, mode: 448 });
+  const temporary = join19(dirname9(file), `.${file.endsWith("cloud.json") ? "hub-binding-cloud" : "hub-binding"}-${process.pid}.tmp`);
+  try {
+    writeFileSync8(temporary, `${JSON.stringify(value, null, 2)}
+`, { encoding: "utf8", mode: 384 });
+    renameSync2(temporary, file);
+  } finally {
+    rmSync2(temporary, { force: true });
+  }
+}
+function parseBindingObject(file) {
+  if (!existsSync16(file)) return new HubBindingError(`missing hub binding at ${file}`);
   let parsed;
   try {
     parsed = JSON.parse(readFileSync14(file, "utf8"));
   } catch {
-    throw new HubBindingError(`malformed hub binding at ${file}`);
+    return new HubBindingError(`malformed hub binding at ${file}`);
   }
   if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw new HubBindingError(`malformed hub binding at ${file}`);
-  }
-  const row = parsed;
-  const keys = Object.keys(row);
-  const allowed = /* @__PURE__ */ new Set(["schema", "url", "boundAt", "cloud", "tokenEnv", "tokenCommand"]);
-  const cloudish = keys.some((key) => key === "cloud" || key === "tokenEnv" || key === "tokenCommand");
-  if (keys.some((key) => !allowed.has(key)) || !cloudish && keys.length !== 3 || row.schema !== HUB_BINDING_SCHEMA || typeof row.url !== "string" || typeof row.boundAt !== "string" || !isIsoTimestamp(row.boundAt)) {
-    throw new HubBindingError(`malformed hub binding at ${file}`);
+    return new HubBindingError(`malformed hub binding at ${file}`);
   }
-  let url;
-  try {
-    url = validateHubUrl(row.url);
-  } catch {
-    throw new HubBindingError(`malformed hub binding at ${file}`);
-  }
-  if (!cloudish) return { schema: HUB_BINDING_SCHEMA, url, boundAt: row.boundAt };
-  if (row.cloud !== true) throw new HubBindingError(`malformed hub binding at ${file}`);
+  return parsed;
+}
+function cloudRecordFromRow(file, row, url, boundAt) {
+  if (row.cloud !== true) return void 0;
   let tokenEnv;
   let tokenCommand;
   if (row.tokenEnv !== void 0) {
@@ -31825,12 +31954,65 @@ function readHubBinding(env = process.env) {
   return {
     schema: HUB_BINDING_SCHEMA,
     url,
-    boundAt: row.boundAt,
+    boundAt,
     cloud: true,
     ...tokenEnv ? { tokenEnv } : {},
     ...tokenCommand ? { tokenCommand } : {}
   };
 }
+function interpretBindingFile(file) {
+  if (!existsSync16(file)) return {};
+  const parsed = parseBindingObject(file);
+  if (parsed instanceof HubBindingError) throw parsed;
+  const keys = Object.keys(parsed);
+  const unknown = keys.filter((key) => !BINDING_KEYS.has(key));
+  if (parsed.schema !== HUB_BINDING_SCHEMA || unknown.length > 0) {
+    return { warning: bindingFallbackWarning(file, `is newer than this build understands (${String(parsed.schema)})`) };
+  }
+  if (typeof parsed.url !== "string" || typeof parsed.boundAt !== "string" || !isIsoTimestamp(parsed.boundAt)) {
+    throw new HubBindingError(`malformed hub binding at ${file}`);
+  }
+  let url;
+  try {
+    url = validateHubUrl(parsed.url);
+  } catch {
+    throw new HubBindingError(`malformed hub binding at ${file}`);
+  }
+  const cloudish = keys.some((key) => key === "cloud" || key === "tokenEnv" || key === "tokenCommand");
+  if (!cloudish) {
+    if (keys.length !== 3) throw new HubBindingError(`malformed hub binding at ${file}`);
+    return { record: { schema: HUB_BINDING_SCHEMA, url, boundAt: parsed.boundAt } };
+  }
+  const record2 = cloudRecordFromRow(file, parsed, url, parsed.boundAt);
+  if (!record2) throw new HubBindingError(`malformed hub binding at ${file}`);
+  return { record: record2, legacyCloud: true };
+}
+function loadHubBinding(env = process.env) {
+  const cloudFile = hubBindingCloudFile(env);
+  const cloud = interpretBindingFile(cloudFile);
+  if (cloud.warning && !cloud.record) {
+    const local = existsSync16(hubBindingFile(env)) ? interpretBindingFile(hubBindingFile(env)) : {};
+    if (local.record && !local.record.cloud) return { record: local.record, warning: cloud.warning };
+    return { warning: cloud.warning };
+  }
+  if (cloud.record?.cloud) return { record: cloud.record, ...cloud.warning ? { warning: cloud.warning } : {} };
+  const main = interpretBindingFile(hubBindingFile(env));
+  if (main.legacyCloud && main.record) {
+    writeBindingJson(cloudFile, main.record);
+    rmSync2(hubBindingFile(env), { force: true });
+    return {
+      record: main.record,
+      warning: bindingFallbackWarning(
+        hubBindingFile(env),
+        "stored a cloud bind in the pre-0.7.160 file"
+      )
+    };
+  }
+  return { ...main.record ? { record: main.record } : {}, ...main.warning ? { warning: main.warning } : {} };
+}
+function readHubBinding(env = process.env) {
+  return loadHubBinding(env).record;
+}
 
 // plugins/kxm/src/hub-env.ts
 import { existsSync as existsSync18, mkdirSync as mkdirSync8, readFileSync as readFileSync16, renameSync as renameSync3, rmSync as rmSync3, writeFileSync as writeFileSync9 } from "node:fs";
@@ -31906,15 +32088,6 @@ function resolveProjectIdentity(cwd, env = process.env, explicit) {
   if (fromPackage) return { project: fromPackage, source: "package.json", sourceLabel: "package.json name" };
   return { project: basename4(cwd), source: "directory", sourceLabel: "directory name" };
 }
-function opReferenceFromTokenCommand(command) {
-  try {
-    const args = splitTokenCommand(command);
-    if (args[0] === "op" && args[1] === "read" && args[2] && isHubOpReference(args[2])) return args[2];
-  } catch {
-    return void 0;
-  }
-  return void 0;
-}
 function defaultOpRead(reference, env) {
   if (!isHubOpReference(reference)) {
     throw new CloudTokenError("cloud_token_command_invalid", `refusing to resolve ${reference}; an op:// reference is required`);
@@ -31959,18 +32132,24 @@ function resolveKeyReference(ref, env, opRead = defaultOpRead) {
 }
 function keySourceFor(input) {
   const ref = input.endpoint?.key;
-  if (input.mode === "local" && input.env.KXM_AUTH_TOKEN?.trim()) return "env:KXM_AUTH_TOKEN";
-  if (ref?.env && input.env[ref.env]?.trim()) return `env:${ref.env}`;
-  if (ref?.op) return `op:${ref.op}`;
-  if (ref?.env) return `env:${ref.env}`;
+  const envName = (name) => {
+    if (!name) return void 0;
+    return input.env[name]?.trim() ? `env:${name}` : void 0;
+  };
   if (input.mode === "cloud") {
-    if (input.binding?.tokenEnv) return `env:${input.binding.tokenEnv}`;
-    if (input.binding?.tokenCommand) {
-      const op = opReferenceFromTokenCommand(input.binding.tokenCommand);
-      return op ? `op:${op}` : "command";
-    }
+    const fromEnv2 = envName(ref?.env);
+    if (fromEnv2) return fromEnv2;
+    if (ref?.op) return `op:${ref.op}`;
+    const fromBindingEnv = envName(input.binding?.tokenEnv);
+    if (fromBindingEnv) return fromBindingEnv;
+    if (input.binding?.tokenCommand) return "token-command";
     return "missing";
   }
+  const fromAuth = envName("KXM_AUTH_TOKEN");
+  if (fromAuth) return fromAuth;
+  const fromEnv = envName(ref?.env);
+  if (fromEnv) return fromEnv;
+  if (ref?.op) return `op:${ref.op}`;
   if (input.hasSavedProjectToken?.(input.project)) return "hub-env";
   return "missing";
 }
@@ -32631,8 +32810,17 @@ async function syncKxmOutbox(eventStore, client, options = {}) {
     }
   }
 }
-function runtimeHubClientFor(context, env) {
-  const serverUrl = env.KXM_SERVER_URL?.trim() || readHubBinding(env)?.url;
+function runtimeHubClientFor(context, env, onBindingWarning) {
+  let recordUrl;
+  try {
+    const loaded = loadHubBinding(env);
+    if (loaded.warning) onBindingWarning?.(loaded.warning);
+    recordUrl = loaded.record?.url;
+  } catch (error) {
+    if (!(error instanceof HubBindingError)) throw error;
+    onBindingWarning?.(`${error.message}; falling back to the local hub so sync can continue`);
+  }
+  const serverUrl = env.KXM_SERVER_URL?.trim() || recordUrl;
   if (!serverUrl) return void 0;
   const project = context.projectId;
   const authToken = resolveClientHubAuthToken(env, project);
@@ -33160,6 +33348,7 @@ async function startKxmRuntimeSupervisorInner(paths, requestedPortOption, now, e
     else logger.info(entry);
   };
   let syncing = false;
+  let bindingWarning;
   const syncTimer = setInterval(() => {
     if (syncing || stopping) return;
     syncing = true;
@@ -33177,7 +33366,11 @@ async function startKxmRuntimeSupervisorInner(paths, requestedPortOption, now, e
           consecutiveFailures: 0
         };
         try {
-          const client = runtimeHubClientFor(context, env);
+          const client = runtimeHubClientFor(context, env, (message) => {
+            if (bindingWarning === message) return;
+            bindingWarning = message;
+            logger.warn({ event: "hub_binding_fallback", message });
+          });
           if (!client) {
             recordSyncStatus(context, { ...base, state: "no_hub" });
             continue;