omp-conductor 0.3.24 → 0.4.0

package/src/release-policy.ts

@@ -1,18 +1,40 @@
+/**
+ * The release/deploy tool-call tripwire.
+ *
+ * **Defence in depth, and no longer load-bearing (#126).** This module works by
+ * pattern-matching a tool name or a shell string inside the session, which is
+ * the weakest place a rule can live: the string is the model's, the matching is
+ * a regex, and `bash` hands it an unbounded alphabet to spell `npm publish` in.
+ * It was the only mechanism there was, and it was never the one anybody should
+ * have had to rely on.
+ *
+ * What actually stops a release now is that the session cannot perform one. It
+ * holds no credential (#125) and its only route to a mutation is the mediated
+ * verbs, whose checks run in the daemon against the configured holder
+ * (`verbs/server.ts`). A worker that talks its way past every regex below still
+ * has nothing to push with.
+ *
+ * It stays installed anyway, for the two things a tripwire is good at and a
+ * boundary is not: it refuses *early*, in the session, with an explanation the
+ * model can act on in the same turn instead of an `EACCES` it may read as
+ * transient; and it leaves a durable record that something tried
+ * ({@link recordReleaseBlock}), which is how drift shows up in a digest rather
+ * than in an incident. Treat a block here as evidence about a session's
+ * intentions, never as proof that the release was prevented — the daemon is
+ * what prevented it.
+ *
+ * {@link releaseRefusal} is the exception to all of the above: it is the shared
+ * grant comparison, and `conductor_release` calls exactly this function, so the
+ * refusal an operator reads is worded once.
+ */
 import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import { stateDir } from "./config.ts";
-import type { ReleasePolicy } from "./types.ts";
+import type { ReleaseShape, ResolvedGrants, SessionRole } from "./types.ts";
 
 export const RELEASE_POLICY_AUDIT_FILE = "release-policy-blocks.jsonl";
 
-export type ReleaseShape =
-  | "git-tag"
-  | "git-push-tags"
-  | "package-publish"
-  | "github-release"
-  | "deploy";
-
 export interface ReleaseBlock {
   project: string;
   source: "worker" | "orchestrator";
@@ -66,6 +88,122 @@ export function releaseShapeFromCommand(command: string): ReleaseShape | undefin
   return undefined;
 }
 
+/**
+ * The tokens a tool name or device path is matched on: split on every separator
+ * (`_`, `-`, `.`, `/`, `:`) and on CamelCase boundaries, then lowercased.
+ * `DeployStack` → `[deploy, stack]`; `GetDeploymentStatus` → `[get, deployment,
+ * status]`; `xd://mcp__komodo_DeployStack` → `[xd, mcp, komodo, deploy, stack]`.
+ *
+ * One tokeniser for both branches of {@link releaseShapeFromTool}, because #130
+ * was two matchers disagreeing about the same tool. The device path tested the
+ * whole string with an unbounded `/deploy/i`, so `xd://mcp__komodo_GetDeploymentStatus`
+ * — a read this fleet's orchestrator makes routinely — was *blocked* as a
+ * release action; the native tool name required a delimiter, so
+ * `mcp__komodo_DeployStack`, the real deploy, matched nothing at all. Wrong in
+ * opposite directions, about the same call.
+ *
+ * Exported for the tests: the negative cases are the whole point of this file,
+ * and they are cheaper to state against tokens than against a decision.
+ */
+export function releaseTokens(name: string): string[] {
+  return (
+    name
+      // `DeployStack` → `Deploy Stack`, then `HTTPServer` → `HTTP Server` so an
+      // acronym prefix cannot swallow the verb that follows it.
+      .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+      .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+      .toLowerCase()
+      .split(/[^a-z0-9]+/)
+      .filter((token) => token.length > 0)
+  );
+}
+
+/**
+ * Verbs that make a name a query, whatever nouns follow. `GetDeploymentStatus`,
+ * `ListDeployments` and `describeDeployment` are how an orchestrator reads a
+ * deployment's state, and refusing those as release actions is the live block
+ * #130 was filed for.
+ */
+const READ_VERBS: Record<string, true> = {
+  get: true,
+  list: true,
+  describe: true,
+  inspect: true,
+  read: true,
+  watch: true,
+  show: true,
+  search: true,
+  status: true,
+};
+
+/**
+ * Mutating deploy verbs. The noun `deployment` is deliberately absent: it is
+ * what a read is *about*, never what a call does.
+ *
+ * `apply` and `destroy` are generic enough to catch an unrelated tool
+ * (`ApplyPatch`), and that is the direction this errs on purpose — an
+ * over-refused edit tool is an escalation, a missed IaC call is an incident.
+ */
+const DEPLOY_ACTIONS: Record<string, true> = {
+  deploy: true,
+  redeploy: true,
+  rollout: true,
+  promote: true,
+  apply: true,
+  destroy: true,
+  teardown: true,
+};
+
+/** Publishing an artifact. `published` is a noun and excluded: it is why
+ *  `xd://mcp__x_ListPublishedArtifacts` classified as `package-publish` (#130). */
+const PUBLISH_ACTIONS: Record<string, true> = { publish: true, republish: true };
+
+/** Cutting a GitHub release takes an action *and* the `release` noun, so
+ *  `create_repository` and `list_releases` are each missing half of it. */
+const RELEASE_ACTIONS: Record<string, true> = {
+  create: true,
+  draft: true,
+  cut: true,
+  publish: true,
+  republish: true,
+};
+
+/**
+ * The shape a tokenised tool name or device path names, if any.
+ *
+ * A query name yields nothing whatever its nouns say. The first token drawn from
+ * either vocabulary decides that, because tool names are verb-first
+ * (`ListDeployments`, `DeployStack`) and the leading verb is the act. A trailing
+ * `status` is a query too — `DeployStatus` opens with a mutating verb and still
+ * only asks a question — while a read verb *after* the action verb is not:
+ * `DeployStackAndWatch` deploys.
+ */
+function releaseShapeFromTokens(tokens: readonly string[]): ReleaseShape | undefined {
+  if (tokens[tokens.length - 1] === "status") return undefined;
+  for (const token of tokens) {
+    if (READ_VERBS[token] === true) return undefined;
+    if (
+      DEPLOY_ACTIONS[token] === true ||
+      RELEASE_ACTIONS[token] === true ||
+      PUBLISH_ACTIONS[token] === true
+    ) {
+      break;
+    }
+  }
+
+  // `release` first: `PublishRelease` cuts a GitHub release, it does not publish
+  // a package, and both vocabularies claim `publish`.
+  if (
+    tokens.some((t) => t === "release" || t === "releases") &&
+    tokens.some((t) => RELEASE_ACTIONS[t] === true)
+  ) {
+    return "github-release";
+  }
+  if (tokens.some((t) => PUBLISH_ACTIONS[t] === true)) return "package-publish";
+  if (tokens.some((t) => DEPLOY_ACTIONS[t] === true)) return "deploy";
+  return undefined;
+}
+
 /** Release-shaped device/tool invocations that do not pass through a shell. */
 export function releaseShapeFromTool(
   toolName: string,
@@ -76,37 +214,60 @@ export function releaseShapeFromTool(
     return typeof input.command === "string" ? releaseShapeFromCommand(input.command) : undefined;
   }
 
+  // An MCP tool reached through the device path: the path *is* the tool name, so
+  // it goes through the same tokeniser as a native one. Only `xd://` paths — a
+  // `write` to `src/deploy.ts` is source code, not a deploy.
   const path = typeof input.path === "string" ? input.path : "";
   if (toolName === "write" && path.startsWith("xd://")) {
-    if (/create[_-]release/i.test(path)) return "github-release";
-    if (/publish/i.test(path)) return "package-publish";
-    if (/deploy/i.test(path)) return "deploy";
+    const viaDevice = releaseShapeFromTokens(releaseTokens(path));
+    if (viaDevice !== undefined) return viaDevice;
   }
 
-  const normalized = toolName.toLowerCase().replaceAll("-", "_");
-  if (/create_?release|release_?create/.test(normalized)) return "github-release";
-  if (/(?:^|_)publish(?:$|_)/.test(normalized)) return "package-publish";
-  if (/(?:^|_)deploy(?:$|_)/.test(normalized)) return "deploy";
-  return undefined;
+  return releaseShapeFromTokens(releaseTokens(toolName));
+}
+
+/**
+ * The refusal a `role` session gets for `shape` under `grants`, or `undefined`
+ * when the grant covers it.
+ *
+ * Separate from classification so the external-orchestrator tick can classify
+ * once, consult its own ownership state, and still word the refusal identically.
+ *
+ * The comparison is the whole gate: a grant is an `AuthorityHolder`, so
+ * `"human"` equals no role and refuses every session, and `"worker"` equals no
+ * grant and is refused every shape however permissive the config is (#126).
+ */
+export function releaseRefusal(
+  grants: ResolvedGrants,
+  role: SessionRole,
+  shape: ReleaseShape,
+): ReleaseDecision | undefined {
+  const holder = grants[shape];
+  if (holder === role) return undefined;
+  return {
+    block: true,
+    reason:
+      `Blocked by releasePolicy: ${shape} is granted to "${holder}", and this is a ${role} session. ` +
+      (role === "worker"
+        ? "A worker session never holds a release grant, whatever the config says — report the release " +
+          "as the next step and stop at a green PR."
+        : holder === "human"
+          ? `Only a human may do this. Set releasePolicy.${shape} to "orchestrator" for this project ` +
+            "first, and only once the operator brief carries the procedure to follow."
+          : "Ask the operator which session is meant to hold this grant."),
+  };
 }
 
 export function releaseDecision(
-  policy: ReleasePolicy,
+  grants: ResolvedGrants,
+  role: SessionRole,
   toolName: string,
   input: Record<string, unknown>,
 ): { shape: ReleaseShape; decision: ReleaseDecision } | undefined {
-  if (policy !== "none") return undefined;
   const shape = releaseShapeFromTool(toolName, input);
   if (shape === undefined) return undefined;
-  return {
-    shape,
-    decision: {
-      block: true,
-      reason:
-        `Blocked by releasePolicy=none (${shape}). ` +
-        "Only a human may change the project to operator-brief before release or deploy tools can run.",
-    },
-  };
+  const decision = releaseRefusal(grants, role, shape);
+  return decision === undefined ? undefined : { shape, decision };
 }
 
 interface ReleasePolicyPi {
@@ -121,12 +282,13 @@ interface ReleasePolicyPi {
 
 /** Inline session extension used by workers and the embedded orchestrator. */
 export function releasePolicyTripwire(
-  policy: ReleasePolicy,
+  grants: ResolvedGrants,
+  role: SessionRole,
   onBlocked: (shape: ReleaseShape) => void = () => {},
 ): (pi: ReleasePolicyPi) => void {
   return (pi) => {
     pi.on("tool_call", (event) => {
-      const blocked = releaseDecision(policy, event.toolName, event.input);
+      const blocked = releaseDecision(grants, role, event.toolName, event.input);
       if (blocked === undefined) return undefined;
       try {
         onBlocked(blocked.shape);