@jjlabsio/claude-crew 0.1.33 → 0.1.35

package/scripts/lib/contracts.mjs

@@ -0,0 +1,146 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { pluginPath } from "./pluginRoot.mjs";
+
+const WORKSPACE_ACCESS_VALUES = new Set(["read-only", "workspace-write"]);
+
+export function loadContracts(filePath) {
+  const resolvedPath =
+    filePath === undefined
+      ? pluginPath("data", "agent-contracts.json")
+      : resolve(process.cwd(), filePath);
+  const contracts = JSON.parse(readFileSync(resolvedPath, "utf8"));
+  validateContracts(contracts);
+  return contracts;
+}
+
+export function validateContracts(obj) {
+  const diagnostics = [];
+
+  if (!isPlainObject(obj)) {
+    throw new Error("Invalid agent contracts:\n- <root>: expected object");
+  }
+
+  if (typeof obj.version !== "number") {
+    diagnostics.push("<root>: version must be a number");
+  }
+
+  if (!Array.isArray(obj.roles)) {
+    diagnostics.push("<root>: roles must be an array");
+    throwContractsError(diagnostics);
+  }
+
+  if (obj.roles.length === 0) {
+    diagnostics.push("<root>: roles must not be empty");
+  }
+
+  const seenRoles = new Set();
+  for (const [index, contract] of obj.roles.entries()) {
+    if (isPlainObject(contract) && typeof contract.role === "string") {
+      if (seenRoles.has(contract.role)) {
+        diagnostics.push(`${contract.role}: duplicate role name`);
+      }
+      seenRoles.add(contract.role);
+    }
+    validateRole(contract, index, diagnostics);
+  }
+
+  if (diagnostics.length > 0) {
+    throwContractsError(diagnostics);
+  }
+}
+
+function validateRole(contract, index, diagnostics) {
+  const role = getRoleLabel(contract, index);
+
+  if (!isPlainObject(contract)) {
+    diagnostics.push(`${role}: role contract must be an object`);
+    return;
+  }
+
+  requireField(contract, "role", role, diagnostics);
+  requireField(contract, "inputs", role, diagnostics);
+  requireField(contract, "outputs", role, diagnostics);
+  requireField(contract, "capabilities", role, diagnostics);
+  requireField(contract, "policy", role, diagnostics);
+  requireField(contract, "claudeSubagent", role, diagnostics);
+
+  if (typeof contract.role !== "string") {
+    diagnostics.push(`${role}: role must be a string`);
+  }
+  validateCapabilities(contract.capabilities, role, diagnostics);
+  validatePolicy(contract.policy, role, diagnostics);
+  validateClaudeSubagent(contract.claudeSubagent, role, diagnostics);
+}
+
+function validateCapabilities(capabilities, role, diagnostics) {
+  if (!isPlainObject(capabilities)) {
+    diagnostics.push(`${role}: capabilities must be an object`);
+    return;
+  }
+
+  if (!WORKSPACE_ACCESS_VALUES.has(capabilities.workspaceAccess)) {
+    diagnostics.push(
+      `${role}: capabilities.workspaceAccess must be one of ${Array.from(WORKSPACE_ACCESS_VALUES).join(", ")}`
+    );
+  }
+}
+
+function validatePolicy(policy, role, diagnostics) {
+  if (!isPlainObject(policy)) {
+    diagnostics.push(`${role}: policy must be an object`);
+    return;
+  }
+
+  if (!Number.isInteger(policy.maxAttempts) || policy.maxAttempts < 1) {
+    diagnostics.push(`${role}: policy.maxAttempts must be an integer >= 1`);
+  }
+}
+
+function validateClaudeSubagent(claudeSubagent, role, diagnostics) {
+  if (!isPlainObject(claudeSubagent)) {
+    diagnostics.push(`${role}: claudeSubagent must be an object`);
+    return;
+  }
+
+  validateStringArray(
+    claudeSubagent.tools,
+    `${role}: claudeSubagent.tools`,
+    diagnostics
+  );
+}
+
+function validateStringArray(value, field, diagnostics) {
+  if (!Array.isArray(value)) {
+    diagnostics.push(`${field} must be a string array`);
+    return;
+  }
+
+  for (const [index, item] of value.entries()) {
+    if (typeof item !== "string") {
+      diagnostics.push(`${field}[${index}] must be a string`);
+    }
+  }
+}
+
+function requireField(contract, field, role, diagnostics) {
+  if (!Object.hasOwn(contract, field)) {
+    diagnostics.push(`${role}: missing required field ${field}`);
+  }
+}
+
+function throwContractsError(diagnostics) {
+  throw new Error(`Invalid agent contracts:\n- ${diagnostics.join("\n- ")}`);
+}
+
+function getRoleLabel(contract, index) {
+  if (isPlainObject(contract) && typeof contract.role === "string") {
+    return contract.role;
+  }
+  return `<role-${index}>`;
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}

package/scripts/lib/dispatch.mjs

@@ -0,0 +1,241 @@
+import { spawn } from "node:child_process";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { renderPrompt } from "./render.mjs";
+
+const DEFAULT_COMPANION = fileURLToPath(
+  new URL("../crew-codex-companion.mjs", import.meta.url)
+);
+const AGENT_RESULT_STATUSES = new Set([
+  "complete",
+  "blocked_on_user",
+  "needs_agent",
+  "needs_tool",
+  "failed"
+]);
+
+export class DispatchError extends Error {
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "DispatchError";
+    this.agentResult = options.agentResult ?? null;
+    this.companionPayload = options.companionPayload ?? null;
+    this.exitCode = options.exitCode ?? 1;
+  }
+}
+
+export function formatDispatchProviderGuardMessage(role, provider) {
+  return `dispatch is for Codex provider only. Resolved provider for role '${role}' is '${provider}'. Use 'render' + Agent tool for Claude provider (see crew-agent-runner SKILL.md).`;
+}
+
+export async function dispatch(input) {
+  if (input.resolved?.provider !== "codex") {
+    throw new DispatchError(
+      formatDispatchProviderGuardMessage(
+        input.role,
+        input.resolved?.provider ?? "unknown"
+      ),
+      { exitCode: 2 }
+    );
+  }
+
+  const companion = resolveCompanion(input);
+  await assertResumeCandidate(input.resumeHandle, companion);
+
+  const tmpDir = await mkdtemp(join(tmpdir(), "claude-crew-dispatch-"));
+  const promptFile = join(tmpDir, `${input.role}-prompt.md`);
+
+  try {
+    await writeFile(
+      promptFile,
+      renderPrompt({
+        role: input.role,
+        request: input.request,
+        contract: input.contract
+      }),
+      "utf8"
+    );
+
+    const args = buildTaskArgs(input, promptFile);
+    const execution = await runCompanion(companion, args);
+    const payload = parseCompanionJson(execution.stdout, "task");
+
+    if (payload.crewAgentResultError) {
+      throw new DispatchError(
+        `Companion returned crewAgentResultError: ${payload.crewAgentResultError}`,
+        { companionPayload: payload }
+      );
+    }
+
+    const agentResult = normalizeAgentResult(payload.crewAgentResult, payload.threadId);
+    if (!agentResult) {
+      throw new DispatchError("Companion did not return crewAgentResult.", {
+        companionPayload: payload
+      });
+    }
+
+    if (execution.status !== 0 && agentResult.status !== "failed") {
+      throw new DispatchError(`Companion exited with status ${execution.status}.`, {
+        agentResult,
+        companionPayload: payload
+      });
+    }
+
+    return agentResult;
+  } finally {
+    await rm(tmpDir, { recursive: true, force: true });
+  }
+}
+
+export async function runCompanion(companion, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(companion.command, [...companion.prefixArgs, ...args], {
+      cwd: process.cwd(),
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true
+    });
+
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", reject);
+    child.on("close", (status, signal) => {
+      resolve({
+        status: status ?? 1,
+        signal,
+        stdout,
+        stderr
+      });
+    });
+  });
+}
+
+async function assertResumeCandidate(resumeHandle, companion) {
+  if (!resumeHandle) {
+    return;
+  }
+
+  const execution = await runCompanion(companion, [
+    "task-resume-candidate",
+    "--json"
+  ]);
+  const payload = parseCompanionJson(execution.stdout, "task-resume-candidate");
+  const candidateThreadId = payload?.candidate?.threadId ?? null;
+
+  if (execution.status !== 0) {
+    throw new DispatchError(
+      `Companion resume candidate lookup failed with status ${execution.status}.`,
+      { companionPayload: payload }
+    );
+  }
+
+  if (!candidateThreadId) {
+    throw new DispatchError(`No resume candidate found for ${resumeHandle}.`, {
+      companionPayload: payload
+    });
+  }
+
+  if (candidateThreadId !== resumeHandle) {
+    throw new DispatchError(
+      `Resume handle ${resumeHandle} does not match candidate ${candidateThreadId}.`,
+      { companionPayload: payload }
+    );
+  }
+}
+
+function buildTaskArgs(input, promptFile) {
+  const args = [
+    "task",
+    "--json",
+    "--expect-crew-result",
+    "--prompt-file",
+    promptFile
+  ];
+
+  if (input.resumeHandle) {
+    args.push("--resume-last");
+  }
+
+  if (input.resolved?.codex_sandbox === "workspace-write") {
+    args.push("--write");
+  }
+
+  if (input.resolved?.model) {
+    args.push("--model", input.resolved.model);
+  }
+
+  if (input.resolved?.reasoning) {
+    args.push("--effort", input.resolved.reasoning);
+  }
+
+  return args;
+}
+
+function normalizeAgentResult(value, threadId) {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  if (!AGENT_RESULT_STATUSES.has(value.status)) {
+    return null;
+  }
+
+  return {
+    ...value,
+    questions: Array.isArray(value.questions) ? value.questions : [],
+    requests: Array.isArray(value.requests) ? value.requests : [],
+    error: value.error ?? null,
+    agent_handle: threadId ?? value.agent_handle ?? null
+  };
+}
+
+function parseCompanionJson(stdout, command) {
+  try {
+    return JSON.parse(stdout);
+  } catch (error) {
+    throw new DispatchError(
+      `Companion ${command} did not return JSON: ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
+  }
+}
+
+function resolveCompanion(input = {}) {
+  const nodeScript =
+    input.companionBin ?? process.env.CREW_COMPANION_NODE_BIN ?? null;
+  if (nodeScript) {
+    return {
+      command: process.execPath,
+      prefixArgs: [nodeScript]
+    };
+  }
+
+  const binary = process.env.CREW_COMPANION_BIN ?? DEFAULT_COMPANION;
+  if (isNodeScript(binary)) {
+    return {
+      command: process.execPath,
+      prefixArgs: [binary]
+    };
+  }
+
+  return {
+    command: binary,
+    prefixArgs: []
+  };
+}
+
+function isNodeScript(value) {
+  const name = basename(String(value));
+  return name.endsWith(".mjs") || name.endsWith(".js");
+}

package/scripts/lib/installHooks.mjs

@@ -0,0 +1,136 @@
+import { execFileSync } from "node:child_process";
+import { chmod, mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+
+export const MANAGED_BLOCK = [
+  "# >>> crew-agent-runner managed >>>",
+  "node scripts/crew-agent-runner.mjs validate || {",
+  "  echo \"crew-agent-runner: validate failed. Run 'node scripts/crew-agent-runner.mjs build' to fix drift.\" >&2",
+  "  exit 1",
+  "}",
+  "# <<< crew-agent-runner managed <<<"
+].join("\n");
+
+const START_MARKER = "# >>> crew-agent-runner managed >>>";
+const END_MARKER = "# <<< crew-agent-runner managed <<<";
+const BASH_SHEBANG = "#!/usr/bin/env bash";
+
+export async function installHooks({ root = process.cwd() } = {}) {
+  const projectRoot = resolve(root);
+  if (!(await isPluginSourceRepo(projectRoot))) {
+    throw new Error(
+      "install-hooks is for claude-crew plugin developers only. " +
+        "End users do not need this command (build/validate are dev tools). " +
+        "If you are developing claude-crew, run from the plugin source repo root."
+    );
+  }
+
+  const hooksDir = await resolveHooksDir(projectRoot);
+  const hookPath = join(hooksDir, "pre-commit");
+  await mkdir(hooksDir, { recursive: true });
+
+  const existing = await readUtf8OrNull(hookPath);
+  const base = ensureShebang(existing ?? "");
+  const next = upsertManagedBlock(base, MANAGED_BLOCK);
+
+  if (next !== existing) {
+    await writeFile(hookPath, next, "utf8");
+  }
+  await chmod(hookPath, 0o755);
+
+  return { hookPath };
+}
+
+async function isPluginSourceRepo(root) {
+  try {
+    const pluginJsonPath = join(root, ".claude-plugin", "plugin.json");
+    const packageJsonPath = join(root, "package.json");
+    const pluginJsonStat = await stat(pluginJsonPath);
+    const packageJsonStat = await stat(packageJsonPath);
+    if (!pluginJsonStat.isFile() || !packageJsonStat.isFile()) {
+      return false;
+    }
+
+    const pkg = JSON.parse(await readFile(packageJsonPath, "utf8"));
+    return pkg.name === "@jjlabsio/claude-crew";
+  } catch {
+    return false;
+  }
+}
+
+export function ensureShebang(content) {
+  if (content.startsWith("#!")) {
+    return content;
+  }
+
+  return `${BASH_SHEBANG}\n${content}`;
+}
+
+export function upsertManagedBlock(content, block) {
+  const start = content.indexOf(START_MARKER);
+  if (start !== -1) {
+    const end = content.indexOf(END_MARKER, start + START_MARKER.length);
+    if (end !== -1) {
+      const afterEnd = end + END_MARKER.length;
+      return `${content.slice(0, start)}${block}${content.slice(afterEnd)}`;
+    }
+  }
+
+  const separator = content.length === 0 || content.endsWith("\n") ? "" : "\n";
+  return `${content}${separator}${block}\n`;
+}
+
+async function resolveHooksDir(projectRoot) {
+  const configuredHooksPath = readConfiguredHooksPath(projectRoot);
+  if (configuredHooksPath) {
+    return isAbsolute(configuredHooksPath)
+      ? configuredHooksPath
+      : resolve(projectRoot, configuredHooksPath);
+  }
+
+  const dotGit = join(projectRoot, ".git");
+  try {
+    const dotGitStat = await stat(dotGit);
+    if (dotGitStat.isDirectory()) {
+      return join(dotGit, "hooks");
+    }
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return join(dotGit, "hooks");
+    }
+    throw error;
+  }
+
+  const gitFile = await readFile(dotGit, "utf8");
+  const match = /^gitdir:\s*(.+)\s*$/m.exec(gitFile);
+  if (!match) {
+    throw new Error(".git is not a directory or gitdir file");
+  }
+
+  const gitDir = match[1];
+  return join(isAbsolute(gitDir) ? gitDir : resolve(dirname(dotGit), gitDir), "hooks");
+}
+
+function readConfiguredHooksPath(projectRoot) {
+  try {
+    const hooksPath = execFileSync(
+      "git",
+      ["-C", projectRoot, "config", "--get", "core.hooksPath"],
+      { encoding: "utf8" }
+    ).trim();
+    return hooksPath || null;
+  } catch {
+    return null;
+  }
+}
+
+async function readUtf8OrNull(path) {
+  try {
+    return await readFile(path, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return null;
+    }
+    throw error;
+  }
+}

package/scripts/lib/pluginRoot.mjs

@@ -0,0 +1,10 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+export const PLUGIN_ROOT = resolve(HERE, "..", "..");
+
+export function pluginPath(...segments) {
+  return resolve(PLUGIN_ROOT, ...segments);
+}

package/scripts/lib/prepare.mjs

@@ -0,0 +1,37 @@
+import { renderPrompt } from "./render.mjs";
+import { pluginPath } from "./pluginRoot.mjs";
+
+export function prepareDispatch({ role, requestFile, request, resolved }) {
+  if (resolved.provider === "codex") {
+    return {
+      role,
+      provider: "codex",
+      action: "dispatch",
+      command: [
+        "node",
+        pluginPath("scripts", "crew-agent-runner.mjs"),
+        "dispatch",
+        "--role",
+        role,
+        "--request-file",
+        requestFile,
+        "--json"
+      ],
+      resolved
+    };
+  }
+
+  return {
+    role,
+    provider: "claude",
+    action: "agent",
+    subagent_type: role,
+    model: resolved.model,
+    prompt: renderPrompt({
+      role,
+      request,
+      contract: resolved.contract
+    }),
+    resolved
+  };
+}

package/scripts/lib/render.mjs

@@ -0,0 +1,138 @@
+export function renderPrompt(input) {
+  const { role, request = {}, contract = {} } = input;
+  const parts = [
+    `# ${titleCase(role)}`,
+    section("Capability", renderCapability(contract)),
+    section("Inputs", renderInputs(request.inputs, contract.inputs?.denied)),
+    section("Outputs", renderJson(contract.outputs)),
+    section("Instructions", request.instruction, { required: true }),
+    section("Success Gate", request.successGate),
+    section("Failure Handling", request.failureHandling),
+    section("AgentResult Contract", renderAgentResultContract())
+  ].filter(Boolean);
+
+  return `${parts.join("\n\n")}\n`;
+}
+
+export function section(title, body, options = {}) {
+  const renderedBody = normalizeBody(body);
+  if (renderedBody.length === 0) {
+    if (options.required) {
+      return `## ${title}`;
+    }
+    return "";
+  }
+
+  return `## ${title}\n${renderedBody}`;
+}
+
+export function fenceBlock(body, fence = "---") {
+  return `${fence}\n${normalizeBlockBody(body)}\n${fence}`;
+}
+
+function renderCapability(contract) {
+  const tools = Array.isArray(contract.claudeSubagent?.tools)
+    ? contract.claudeSubagent.tools
+    : [];
+  const outputs = Array.isArray(contract.outputs) ? contract.outputs : [];
+
+  return [
+    `workspaceAccess: ${contract.capabilities?.workspaceAccess ?? "unknown"}`,
+    `canAskUser: ${String(tools.includes("AskUserQuestion"))}`,
+    `canRequestAgent: ${String(tools.includes("Agent"))}`,
+    `canUseShell: ${String(tools.includes("Bash"))}`,
+    `canWriteCrewFiles: ${String(canWriteCrewFiles(outputs))}`
+  ].join("\n");
+}
+
+function renderInputs(inputs, denied) {
+  const lines = [];
+
+  if (Array.isArray(inputs) && inputs.length > 0) {
+    for (const item of inputs) {
+      lines.push(`### ${item.path}`);
+      lines.push(item.content ?? "");
+    }
+  }
+
+  if (Array.isArray(denied) && denied.length > 0) {
+    lines.push("### Denied Inputs");
+    for (const item of denied) {
+      lines.push(`- ${item}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function renderJson(value) {
+  if (value === undefined || value === null) {
+    return "";
+  }
+
+  return JSON.stringify(value, null, 2);
+}
+
+function renderAgentResultContract() {
+  return [
+    "Return exactly one final AgentResult JSON object wrapped in these tags:",
+    "",
+    "```text",
+    "<crew-agent-result>",
+    "{",
+    '  "status": "complete | blocked_on_user | needs_agent | needs_tool | failed",',
+    '  "artifact": null,',
+    '  "questions": [],',
+    '  "requests": [],',
+    '  "summary": "short summary",',
+    '  "error": null',
+    "}",
+    "</crew-agent-result>",
+    "```",
+    "",
+    "Rules:",
+    "- The wrapper tags are mandatory.",
+    "- The JSON inside the tags must be valid JSON.",
+    "- Use complete when the requested artifact is ready.",
+    "- Use blocked_on_user only with a non-empty questions array.",
+    "- Use needs_agent or needs_tool only with a non-empty requests array.",
+    "- Use failed with an error string when the task cannot continue."
+  ].join("\n");
+}
+
+function normalizeBody(body) {
+  if (body === undefined || body === null) {
+    return "";
+  }
+
+  return String(body).trim();
+}
+
+function normalizeBlockBody(body) {
+  if (body === undefined || body === null) {
+    return "";
+  }
+
+  return String(body)
+    .replace(/^\uFEFF/, "")
+    .replace(/\r\n?/g, "\n")
+    .replace(/\n+$/g, "");
+}
+
+function titleCase(value) {
+  return String(value)
+    .split("-")
+    .filter(Boolean)
+    .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+    .join("-");
+}
+
+function canWriteCrewFiles(outputs) {
+  return outputs.some((output) => {
+    return (
+      output?.type === "artifact" &&
+      typeof output.target === "string" &&
+      output.target.startsWith(".crew/")
+    );
+  });
+}