@jjlabsio/claude-crew 0.1.32 → 0.1.34

package/scripts/lib/build.mjs

@@ -0,0 +1,213 @@
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+import { loadContracts } from "./contracts.mjs";
+
+const DEFAULT_CONTRACTS_PATH = "data/agent-contracts.json";
+const FALLBACK_CONTRACTS_PATH = "contracts.json";
+const DEFAULT_CATALOG_PATH = "data/provider-catalog.json";
+const FALLBACK_CATALOG_PATH = "provider-catalog.json";
+const DEFAULT_INSTRUCTIONS_DIR = "data/agent-instructions";
+const FALLBACK_INSTRUCTIONS_DIR = "instructions";
+const DEFAULT_PLUGIN_PATH = ".claude-plugin/plugin.json";
+const FALLBACK_PLUGIN_PATH = "plugin.json";
+
+export async function build({ root = process.cwd() } = {}) {
+  const inputs = resolveBuildInputs(resolve(root));
+  const contracts = loadContracts(inputs.contractsPath);
+
+  await warnOrphanInstructions({
+    instructionsDir: inputs.instructionsDir,
+    contracts
+  });
+
+  const derived = await deriveBuildOutput({
+    root,
+    contracts,
+    instructionsDir: inputs.instructionsDir,
+    pluginPath: inputs.pluginPath
+  });
+
+  const agentsDir = join(inputs.projectRoot, "agents");
+  await mkdir(agentsDir, { recursive: true });
+
+  for (const [role, content] of derived.agents.entries()) {
+    await writeFile(join(agentsDir, `${role}.md`), content, "utf8");
+  }
+
+  await writeFile(inputs.pluginPath, derived.pluginJson, "utf8");
+}
+
+export async function deriveBuildOutput({
+  root = process.cwd(),
+  contracts,
+  instructionsDir,
+  pluginPath
+} = {}) {
+  const inputs = resolveBuildInputs(resolve(root));
+  const resolvedContracts =
+    contracts ?? loadContracts(inputs.contractsPath);
+  const resolvedInstructionsDir = instructionsDir ?? inputs.instructionsDir;
+  const resolvedPluginPath = pluginPath ?? inputs.pluginPath;
+
+  const instructionsByRole = new Map();
+  const missingInstructions = [];
+  for (const contract of resolvedContracts.roles) {
+    const role = contract.role;
+    const instructionPath = join(resolvedInstructionsDir, `${role}.md`);
+    if (!existsSync(instructionPath)) {
+      missingInstructions.push(role);
+      continue;
+    }
+
+    instructionsByRole.set(role, await readFile(instructionPath, "utf8"));
+  }
+
+  if (missingInstructions.length > 0) {
+    throw new Error(
+      `Missing agent instructions: ${missingInstructions.join(", ")}`
+    );
+  }
+
+  const agents = new Map();
+  for (const contract of resolvedContracts.roles) {
+    const role = contract.role;
+
+    const model = contract.claudeSubagent?.model;
+    if (typeof model !== "string" || model.length === 0) {
+      throw new Error(`Missing Claude subagent model for role: ${role}`);
+    }
+
+    const agent = renderAgent({
+      contract,
+      model,
+      instructions: instructionsByRole.get(role)
+    });
+    agents.set(role, agent);
+  }
+
+  const plugin = JSON.parse(await readFile(resolvedPluginPath, "utf8"));
+  plugin.agents = resolvedContracts.roles.map(
+    (contract) => `./agents/${contract.role}.md`
+  );
+
+  return {
+    agents,
+    pluginJson: `${JSON.stringify(plugin, null, 2)}\n`
+  };
+}
+
+export function serializeFrontmatter({ name, model, description, tools }) {
+  return [
+    "---",
+    `name: ${name}`,
+    `model: ${model}`,
+    `description: ${description}`,
+    `tools: [${tools.join(", ")}]`,
+    "---"
+  ].join("\n");
+}
+
+function renderAgent({ contract, model, instructions }) {
+  const frontmatter = serializeFrontmatter({
+    name: contract.role,
+    model,
+    description: contract.claudeSubagent.description,
+    tools: contract.claudeSubagent.tools
+  });
+  const body = [renderCapability(contract), normalizeBlockBody(instructions)]
+    .filter(Boolean)
+    .join("\n\n");
+
+  return `${frontmatter}\n\n${body}\n`;
+}
+
+function renderCapability(contract) {
+  const tools = Array.isArray(contract.claudeSubagent?.tools)
+    ? contract.claudeSubagent.tools
+    : [];
+  const outputs = Array.isArray(contract.outputs) ? contract.outputs : [];
+
+  return [
+    "## Capability",
+    `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");
+}
+
+async function warnOrphanInstructions({ instructionsDir, contracts }) {
+  const roles = new Set(contracts.roles.map((contract) => contract.role));
+  const entries = await readdir(instructionsDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".md")) {
+      continue;
+    }
+
+    const role = entry.name.slice(0, -".md".length);
+    if (!roles.has(role)) {
+      console.error(`Warning: instruction file has no contract role: ${role}`);
+    }
+  }
+}
+
+function resolveInput(root, primary, fallback) {
+  const primaryPath = join(root, primary);
+  if (existsSync(primaryPath)) {
+    return primaryPath;
+  }
+
+  const fallbackPath = join(root, fallback);
+  if (existsSync(fallbackPath)) {
+    return fallbackPath;
+  }
+
+  return primaryPath;
+}
+
+export function resolveBuildInputs(root = process.cwd()) {
+  const projectRoot = resolve(root);
+  return {
+    projectRoot,
+    contractsPath: resolveInput(
+      projectRoot,
+      DEFAULT_CONTRACTS_PATH,
+      FALLBACK_CONTRACTS_PATH
+    ),
+    catalogPath: resolveInput(
+      projectRoot,
+      DEFAULT_CATALOG_PATH,
+      FALLBACK_CATALOG_PATH
+    ),
+    instructionsDir: resolveInput(
+      projectRoot,
+      DEFAULT_INSTRUCTIONS_DIR,
+      FALLBACK_INSTRUCTIONS_DIR
+    ),
+    pluginPath: resolveInput(
+      projectRoot,
+      DEFAULT_PLUGIN_PATH,
+      FALLBACK_PLUGIN_PATH
+    )
+  };
+}
+
+function normalizeBlockBody(body) {
+  return String(body)
+    .replace(/^\uFEFF/, "")
+    .replace(/\r\n?/g, "\n")
+    .replace(/\n+$/g, "");
+}
+
+function canWriteCrewFiles(outputs) {
+  return outputs.some((output) => {
+    return (
+      output?.type === "artifact" &&
+      typeof output.target === "string" &&
+      output.target.startsWith(".crew/")
+    );
+  });
+}

package/scripts/lib/cli.mjs

@@ -0,0 +1,30 @@
+export function parseArgv(argv) {
+  const positional = [];
+  const flags = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (!arg.startsWith("--") || arg === "--") {
+      positional.push(arg);
+      continue;
+    }
+
+    const key = arg.slice(2);
+    if (key.length === 0) {
+      positional.push(arg);
+      continue;
+    }
+
+    const next = argv[index + 1];
+    if (next === undefined || next.startsWith("--")) {
+      flags[key] = true;
+      continue;
+    }
+
+    flags[key] = next;
+    index += 1;
+  }
+
+  return { positional, flags };
+}

package/scripts/lib/config.mjs

@@ -0,0 +1,33 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+
+import { pluginPath } from "./pluginRoot.mjs";
+
+export function loadCatalog(filePath) {
+  return readJson(
+    filePath === undefined
+      ? pluginPath("data", "provider-catalog.json")
+      : resolve(process.cwd(), filePath),
+    true
+  );
+}
+
+export function loadUserConfig(filePath = join(homedir(), ".claude", "crew", "config.json")) {
+  return readJson(filePath, true);
+}
+
+export function loadProjectConfig(projectRoot = process.cwd()) {
+  return readJson(join(projectRoot, ".crew", "config.json"), true);
+}
+
+function readJson(filePath, allowMissing) {
+  if (!existsSync(filePath)) {
+    if (allowMissing) {
+      return {};
+    }
+    throw new Error(`File not found: ${filePath}`);
+  }
+
+  return JSON.parse(readFileSync(filePath, "utf8"));
+}

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");
+}