@orchestrator-claude/definitions 3.33.0 → 3.35.0

package/hooks/playwright-output-guard.ts

@@ -0,0 +1,130 @@
+/**
+ * playwright-output-guard.ts — PreToolUse[browser_take_screenshot] hook (S269 item g)
+ *
+ * Problema: @playwright/mcp resolve `filename` contra o WORKSPACE ROOT
+ * (workspaceFile em packages/playwright-core/src/tools/backend/context.ts),
+ * não contra o outputDir. Filenames sem diretório caem na raiz do repo e o
+ * auto-checkpoint (`git add -A`) varre os PNGs para dentro de commits —
+ * recorrência observada em S266/S267/S268.
+ *
+ * Fix em camadas:
+ *   1. Este hook NEGA filenames que resolveriam para a raiz do projeto,
+ *      instruindo o agente a usar `.playwright-mcp/` (gitignored) ou
+ *      `.cobaia-evidence/<sessão>/` (evidência versionável).
+ *   2. `.gitignore` com `/*.png` etc. como cinto-e-suspensório.
+ *
+ * Política:
+ *   - sem filename            → ALLOW (default = <cwd>/.playwright-mcp/, gitignored)
+ *   - filename em subdiretório → ALLOW
+ *   - filename bare / ./x.png / absoluto-na-raiz / traversal → DENY
+ *   - stdin não-parseável     → ALLOW (fail-open: nunca bloquear por infra)
+ */
+
+import { dirname, isAbsolute, normalize, resolve } from 'node:path';
+import {
+  log,
+  readStdin,
+  getField,
+  outputPreToolUse,
+  resolveHookProjectRoot,
+} from './lib/api-client.js';
+
+const HOOK = 'PLAYWRIGHT-OUTPUT-GUARD';
+
+/**
+ * Raiz do projeto contra a qual `filename` é resolvido.
+ *
+ * ⚠️ NÃO derive de `__filename` (era o bug, S396/RFC-040 §18.12): sob o modelo
+ * de distribuição por plugin (§18) este arquivo roda a partir de
+ * `~/.claude/plugins/cache/<marketplace>/orchestrator/<versão>/hooks/`, então
+ * `dirname(__filename)/../..` resolveria para o CACHE DO PLUGIN em vez do repo
+ * do usuário. O guard não quebraria (fail-open), mas `dir === PROJECT_ROOT`
+ * nunca casaria — viraria um NO-OP SILENCIOSO, a pior falha possível para um
+ * gate. Cadeia de resolução, do mais autoritativo ao último recurso:
+ *   1. `CLAUDE_PROJECT_DIR` — injetado pelo harness, correto por construção;
+ *   2. walk-up pelo sentinel `.orchestrator` (primitivo RFC-040 C1);
+ *   3. `process.cwd()` — hooks rodam com cwd = diretório do projeto.
+ */
+export const PROJECT_ROOT =
+  process.env.CLAUDE_PROJECT_DIR ?? resolveHookProjectRoot(process.cwd()) ?? process.cwd();
+
+export interface GuardDecision {
+  decision: 'allow' | 'deny';
+  reason?: string;
+}
+
+const GUIDANCE =
+  'Playwright Output Guard: screenshots não podem cair na raiz do repo (auto-checkpoint os varre — recorrência S266-S268). ' +
+  'Use `filename: ".playwright-mcp/<nome>.png"` (descartável, gitignored), ' +
+  '`filename: ".cobaia-evidence/<sessão>/<nome>.png"` (evidência a versionar), ' +
+  'ou omita `filename` (default já vai para .playwright-mcp/).';
+
+/**
+ * Avalia o filename pedido pelo agente.
+ * DENY quando o arquivo resolveria para a raiz do projeto (ou acima dela).
+ */
+export function evaluateFilename(filename: string | undefined): GuardDecision {
+  if (!filename) return { decision: 'allow' };
+
+  const resolved = isAbsolute(filename) ? normalize(filename) : resolve(PROJECT_ROOT, filename);
+
+  const dir = dirname(resolved);
+
+  // Cairia exatamente na raiz do projeto → DENY
+  if (dir === PROJECT_ROOT) {
+    return { decision: 'deny', reason: GUIDANCE };
+  }
+
+  // Traversal para fora do projeto → DENY (o próprio MCP também negaria,
+  // mas aqui damos guidance acionável em vez de erro críptico)
+  if (!resolved.startsWith(PROJECT_ROOT + '/') && !isAbsolute(filename)) {
+    return { decision: 'deny', reason: GUIDANCE };
+  }
+
+  return { decision: 'allow' };
+}
+
+// ─────────────────────────────────────────────────────────────
+// Dependency injection (testável sem IO)
+// ─────────────────────────────────────────────────────────────
+
+export interface HookDeps {
+  readStdin: () => Promise<Record<string, unknown>>;
+  output: (opts: { decision: 'allow' | 'deny'; reason?: string; context?: string }) => void;
+  log: (prefix: string, msg: string) => void;
+}
+
+const defaultDeps: HookDeps = {
+  readStdin,
+  output: outputPreToolUse,
+  log,
+};
+
+export async function mainWithDeps(deps: HookDeps): Promise<void> {
+  const stdin = await deps.readStdin();
+  const filename = getField(stdin, 'tool_input.filename');
+
+  const result = evaluateFilename(filename || undefined);
+  deps.log(HOOK, `filename=${filename || '(none)'} decision=${result.decision}`);
+
+  if (result.decision === 'deny') {
+    deps.output({ decision: 'deny', reason: result.reason });
+    return;
+  }
+
+  deps.output({
+    decision: 'allow',
+    ...(filename
+      ? {}
+      : {
+          context:
+            '[PLAYWRIGHT-OUTPUT-GUARD] sem filename: output em .playwright-mcp/ (gitignored).',
+        }),
+  });
+}
+
+async function main(): Promise<void> {
+  await mainWithDeps(defaultDeps);
+}
+
+main().catch(() => process.exit(0));

package/hooks/pre-agent-dispatch.mjs

@@ -0,0 +1,346 @@
+import { createRequire as __createRequireShim } from 'node:module'; const require = __createRequireShim(import.meta.url);
+
+// hooks/pre-agent-dispatch.ts
+import { execFileSync } from "node:child_process";
+
+// hooks/lib/api-client.ts
+import { readFileSync, writeFileSync, mkdirSync, statSync, unlinkSync, readdirSync } from "node:fs";
+import { join as join2, dirname as dirname2 } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// ../project-root-resolver/dist/index.js
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+function resolveProjectRoot(cwd, sentinel = ".orchestrator") {
+  let currentDir = cwd;
+  for (; ; ) {
+    if (existsSync(join(currentDir, sentinel))) {
+      return currentDir;
+    }
+    const parentDir = dirname(currentDir);
+    if (parentDir === currentDir) {
+      return null;
+    }
+    currentDir = parentDir;
+  }
+}
+
+// hooks/lib/api-client.ts
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = dirname2(__filename);
+var PROJECT_ROOT = join2(__dirname, "..", "..", "..");
+var STATE_DIR = join2(PROJECT_ROOT, ".orchestrator", ".state");
+var JWT_CACHE = join2(STATE_DIR, "jwt-token");
+var DEBUG_LOG = join2(STATE_DIR, "hook-debug.log");
+mkdirSync(STATE_DIR, { recursive: true });
+var API_URL = process.env.ORCHESTRATOR_API_URL || "http://localhost:3001";
+var AUTH_EMAIL = process.env.ORCHESTRATOR_ADMIN_EMAIL || process.env.ORCHESTRATOR_AUTH_EMAIL || "system@orchestrator.local";
+var AUTH_PASSWORD = process.env.ORCHESTRATOR_ADMIN_PASSWORD || process.env.ORCHESTRATOR_AUTH_PASSWORD || "system123";
+var PROJECT_ID = process.env.ORCHESTRATOR_PROJECT_ID || "";
+function resolveHookProjectRoot(cwd) {
+  return resolveProjectRoot(cwd);
+}
+var projectIdResolutionAttempted = false;
+async function ensureProjectIdResolved(token) {
+  if (PROJECT_ID || projectIdResolutionAttempted) return;
+  projectIdResolutionAttempted = true;
+  try {
+    const rootPath = resolveHookProjectRoot(process.cwd());
+    if (rootPath === null) {
+      log(
+        "API-CLIENT",
+        "ensureProjectIdResolved: cwd not registered (.orchestrator sentinel not found) \u2014 skipping"
+      );
+      return;
+    }
+    const resolved = await resolveProjectIdByPath(rootPath, token);
+    if (resolved) {
+      PROJECT_ID = resolved;
+      log(
+        "API-CLIENT",
+        `ensureProjectIdResolved: resolved projectId=${resolved} rootPath=${rootPath}`
+      );
+    } else {
+      log(
+        "API-CLIENT",
+        `ensureProjectIdResolved: rootPath=${rootPath} not registered to any project \u2014 skipping`
+      );
+    }
+  } catch (err) {
+    log(
+      "API-CLIENT",
+      `ensureProjectIdResolved: unexpected failure \u2014 ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+function log(prefix, msg) {
+  const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/\.\d+Z$/, "Z");
+  try {
+    const line = `[${ts}] ${prefix}: ${msg}
+`;
+    writeFileSync(DEBUG_LOG, line, { flag: "a" });
+  } catch {
+  }
+}
+function getCachedToken() {
+  try {
+    const stat = statSync(JWT_CACHE);
+    const ageMs = Date.now() - stat.mtimeMs;
+    if (ageMs < 35e5) {
+      return readFileSync(JWT_CACHE, "utf-8").trim();
+    }
+  } catch {
+  }
+  return null;
+}
+async function login() {
+  try {
+    const resp = await fetch(`${API_URL}/api/v1/auth/login`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Project-ID": PROJECT_ID
+      },
+      body: JSON.stringify({ email: AUTH_EMAIL, password: AUTH_PASSWORD }),
+      signal: AbortSignal.timeout(5e3)
+    });
+    if (!resp.ok) return null;
+    const data = await resp.json();
+    const token = data.accessToken || data.data?.accessToken || "";
+    if (token) {
+      writeFileSync(JWT_CACHE, token);
+    }
+    return token || null;
+  } catch {
+    return null;
+  }
+}
+async function getToken() {
+  const token = getCachedToken() || await login();
+  if (token) {
+    await ensureProjectIdResolved(token);
+  }
+  return token;
+}
+async function apiGet(path, token, timeoutMs = 5e3) {
+  try {
+    const resp = await fetch(`${API_URL}${path}`, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "X-Project-ID": PROJECT_ID
+      },
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    if (!resp.ok) return null;
+    return await resp.json();
+  } catch {
+    return null;
+  }
+}
+async function resolveProjectIdByPath(rootPath, token) {
+  const resp = await apiGet(
+    `/api/v1/projects/resolve?rootPath=${encodeURIComponent(rootPath)}`,
+    token
+  );
+  return resp?.projectId ?? null;
+}
+async function getActiveWorkflow() {
+  const token = await getToken();
+  if (!token) return null;
+  for (const status of ["in_progress", "awaiting_agent", "awaiting_approval"]) {
+    const resp = await apiGet(
+      `/api/v1/workflows?status=${status}&limit=1`,
+      token,
+      3e3
+    );
+    const list = resp?.data || (Array.isArray(resp) ? resp : null);
+    const wf = list?.[0];
+    if (wf?.id) return wf;
+  }
+  return null;
+}
+var LAST_COMPLETED_FILE = join2(STATE_DIR, "last-completed-workflow.json");
+var LAST_COMPLETED_TTL_MS = 60 * 60 * 1e3;
+var INVOCATIONS_DIR = join2(STATE_DIR, "invocations");
+var INVOCATION_STATE_TTL_MS = 4 * 60 * 60 * 1e3;
+var DISPATCH_INTENT_DIR = join2(STATE_DIR, "dispatch-intent");
+function buildDispatchIntentPath(stateDir, workflowId) {
+  return join2(stateDir, "dispatch-intent", `${workflowId}.json`);
+}
+function writeDispatchIntent(workflowId) {
+  try {
+    mkdirSync(DISPATCH_INTENT_DIR, { recursive: true });
+    const path = buildDispatchIntentPath(STATE_DIR, workflowId);
+    const payload = { workflowId, stampedAt: (/* @__PURE__ */ new Date()).toISOString() };
+    writeFileSync(path, JSON.stringify(payload), "utf-8");
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk);
+  }
+  const raw = Buffer.concat(chunks).toString("utf-8").trim();
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+function getField(obj, path) {
+  const parts = path.split(".");
+  let current = obj;
+  for (const part of parts) {
+    if (current == null || typeof current !== "object") return "";
+    current = current[part];
+  }
+  return current != null ? String(current) : "";
+}
+function outputContext(hookEvent, context) {
+  console.log(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: hookEvent,
+        additionalContext: context
+      }
+    })
+  );
+}
+
+// hooks/pre-agent-dispatch.ts
+var HOOK = "PRE-AGENT-DISPATCH";
+var KNOWN_AGENTS = [
+  "implementer",
+  "planner",
+  "specifier",
+  "reviewer",
+  "task-generator",
+  "researcher"
+];
+var KNOWN_AGENTS_REGEX = new RegExp(`\\b(${KNOWN_AGENTS.join("|")})\\b`, "i");
+var COMMITTING_AGENTS = [
+  "implementer",
+  "azure-devops-engineer",
+  "presentation-engineer",
+  "operational-artifact-builder",
+  "cicd-platform-engineer",
+  "python-data-engineer",
+  "frontend-engineer"
+];
+var PROTECTED_BRANCHES = ["main", "master"];
+function normalizeAgentName(subagentType) {
+  const i = subagentType.lastIndexOf(":");
+  return i === -1 ? subagentType : subagentType.slice(i + 1);
+}
+function isCommittingAgent(subagentType) {
+  if (!subagentType) return false;
+  const t = normalizeAgentName(subagentType).toLowerCase();
+  if (!t) return false;
+  return COMMITTING_AGENTS.some((a) => a.toLowerCase() === t);
+}
+function isProtectedBranch(branch) {
+  return PROTECTED_BRANCHES.includes(branch);
+}
+function parseBranchFromHead(headContents) {
+  const m = /^ref:\s*refs\/heads\/(.+)$/.exec(headContents.trim());
+  return m ? (m[1] ?? "").trim() : "";
+}
+function detectKnownAgentInPrompt(prompt) {
+  const match = KNOWN_AGENTS_REGEX.exec(prompt);
+  return match ? (match[1] ?? "").toLowerCase() : null;
+}
+function branchBeforeDispatchMessage(subagentType, branch) {
+  return `[BRANCH-BEFORE-DISPATCH][TD-171] About to dispatch committing agent '${subagentType}' while on protected branch '${branch}'. This agent can make LOCAL checkpoint commits, and agent-git-guard (TD-169) blocks push/merge but ALLOWS commit \u2014 so a local commit would land directly on '${branch}' (root cause of the S289 '4f1f4f37' breach). Check out a feature branch BEFORE dispatching; the orchestrator owns push after its independent assert.`;
+}
+function evaluateDispatch(ctx) {
+  const warnings = [];
+  const { subagentType, prompt, branch } = ctx;
+  if (!subagentType) {
+    const detected = detectKnownAgentInPrompt(prompt);
+    if (detected) {
+      warnings.push(
+        `[WARN] Agent dispatched without subagent_type. Known agent detected: "${detected}". Add subagent_type for proper frontmatter loading.`
+      );
+    }
+  }
+  if (isCommittingAgent(subagentType) && isProtectedBranch(branch)) {
+    warnings.push(branchBeforeDispatchMessage(subagentType, branch));
+  }
+  return warnings;
+}
+function readBranchFromGit() {
+  try {
+    return execFileSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+var defaultDeps = {
+  readStdin,
+  outputContext,
+  log,
+  readBranch: readBranchFromGit,
+  getActiveWorkflow,
+  writeDispatchIntent
+};
+var DISPATCH_INTENT_RESOLVE_TIMEOUT_MS = 3e3;
+async function stampDispatchIntent(deps) {
+  if (!deps.getActiveWorkflow || !deps.writeDispatchIntent) return;
+  try {
+    const workflow = await Promise.race([
+      deps.getActiveWorkflow(),
+      new Promise((resolve) => {
+        setTimeout(() => {
+          resolve(null);
+        }, DISPATCH_INTENT_RESOLVE_TIMEOUT_MS);
+      })
+    ]);
+    if (workflow?.id) {
+      const stamped = deps.writeDispatchIntent(workflow.id);
+      deps.log(HOOK, `[TD-205] dispatch-intent stamped=${String(stamped)} workflow=${workflow.id}`);
+    }
+  } catch (err) {
+    deps.log(HOOK, `[TD-205] stampDispatchIntent failed (fail-open): ${String(err)}`);
+  }
+}
+async function mainWithDeps(deps) {
+  const stdin = await deps.readStdin();
+  const toolInput = getField(stdin, "tool_input") || "";
+  const subagentType = getField(stdin, "tool_input.subagent_type") || getField(stdin, "tool_input.subagentType") || "";
+  const prompt = getField(stdin, "tool_input.prompt") || getField(stdin, "tool_input.description") || (typeof toolInput === "string" ? toolInput : JSON.stringify(toolInput));
+  const branch = deps.readBranch();
+  const warnings = evaluateDispatch({ subagentType, prompt, branch });
+  await stampDispatchIntent(deps);
+  if (warnings.length > 0) {
+    deps.outputContext(HOOK, warnings.join("\n"));
+    deps.log(
+      HOOK,
+      `${warnings.length} warning(s) (agent="${subagentType || "?"}" branch="${branch}")`
+    );
+    return;
+  }
+  deps.log(HOOK, `OK (agent="${subagentType || "?"}" branch="${branch}")`);
+}
+async function main() {
+  await mainWithDeps(defaultDeps);
+}
+main().catch(() => process.exit(0));
+export {
+  COMMITTING_AGENTS,
+  branchBeforeDispatchMessage,
+  detectKnownAgentInPrompt,
+  evaluateDispatch,
+  isCommittingAgent,
+  isProtectedBranch,
+  mainWithDeps,
+  normalizeAgentName,
+  parseBranchFromHead,
+  stampDispatchIntent
+};