bopodev-agent-sdk 0.1.1

package/src/runtime.ts

@@ -0,0 +1,585 @@
+import { spawn } from "node:child_process";
+import { access, lstat, mkdir, mkdtemp, readdir, rm, symlink } from "node:fs/promises";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { AgentRuntimeConfig } from "./types";
+
+export interface RuntimeExecutionOutput {
+  ok: boolean;
+  code: number | null;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+  elapsedMs: number;
+  attemptCount: number;
+  failureType?: "timeout" | "spawn_error" | "nonzero_exit";
+  attempts: RuntimeAttemptTrace[];
+  parsedUsage?: {
+    tokenInput?: number;
+    tokenOutput?: number;
+    usdCost?: number;
+    summary?: string;
+    executionMode?: "local_work" | "control_plane";
+    gatedControlPlaneReasons?: string[];
+  };
+}
+
+export interface RuntimeAttemptTrace {
+  attempt: number;
+  code: number | null;
+  timedOut: boolean;
+  elapsedMs: number;
+  signal: NodeJS.Signals | null;
+  spawnErrorCode?: string;
+  forcedKill: boolean;
+}
+
+export interface RuntimeCommandHealth {
+  command: string;
+  available: boolean;
+  exitCode: number | null;
+  elapsedMs: number;
+  error?: string;
+}
+
+function pickDefaultCommand(provider: "claude_code" | "codex") {
+  if (provider === "claude_code") {
+    return "claude";
+  }
+  return "codex";
+}
+
+function providerDefaultArgs(provider: "claude_code" | "codex") {
+  if (provider === "claude_code") {
+    return ["-p"];
+  }
+  // Keep Codex non-interactive, sandboxed, and writable in-workspace by default.
+  // This avoids inheriting read-only profiles that can cause flaky heartbeat failures.
+  return ["exec", "--full-auto"];
+}
+
+export async function executeAgentRuntime(
+  provider: "claude_code" | "codex",
+  prompt: string,
+  config?: AgentRuntimeConfig
+): Promise<RuntimeExecutionOutput> {
+  const commandOverride = Boolean(config?.command && config.command.trim().length > 0);
+  const effectiveRetryCount = config?.retryCount ?? (provider === "codex" ? 1 : 0);
+  const mergedArgs = [
+    ...(commandOverride ? [] : providerDefaultArgs(provider)),
+    ...(config?.args ?? [])
+  ];
+  return executePromptRuntime(
+    config?.command ?? pickDefaultCommand(provider),
+    prompt,
+    { ...config, args: mergedArgs, retryCount: effectiveRetryCount },
+    {
+      provider
+    }
+  );
+}
+
+export async function executePromptRuntime(
+  command: string,
+  prompt: string,
+  config?: AgentRuntimeConfig,
+  options?: { provider?: "claude_code" | "codex" }
+): Promise<RuntimeExecutionOutput> {
+  const baseArgs = [...(config?.args ?? [])];
+  const timeoutMs = config?.timeoutMs ?? 120_000;
+  const maxAttempts = Math.max(1, Math.min(3, 1 + (config?.retryCount ?? 0)));
+  const retryBackoffMs = Math.max(100, config?.retryBackoffMs ?? 400);
+  const env = {
+    ...process.env,
+    ...(config?.env ?? {})
+  };
+  const provider = options?.provider;
+  const injection = await prepareSkillInjection(provider, env);
+  const args = [...baseArgs, ...injection.additionalArgs, prompt];
+  const attempts: RuntimeAttemptTrace[] = [];
+  let stdout = "";
+  let stderr = injection.warning ? `${injection.warning}\n` : "";
+  let lastResult:
+    | {
+        code: number | null;
+        timedOut: boolean;
+        elapsedMs: number;
+        signal: NodeJS.Signals | null;
+        spawnErrorCode?: string;
+        forcedKill: boolean;
+      }
+    | undefined;
+  try {
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+      const attemptResult = await executeSinglePromptAttempt(command, args, config?.cwd || process.cwd(), env, timeoutMs);
+      stdout += attemptResult.stdout;
+      stderr = [stderr, attemptResult.stderr].filter(Boolean).join("\n").trim();
+      attempts.push({
+        attempt,
+        code: attemptResult.code,
+        timedOut: attemptResult.timedOut,
+        elapsedMs: attemptResult.elapsedMs,
+        signal: attemptResult.signal,
+        spawnErrorCode: attemptResult.spawnErrorCode,
+        forcedKill: attemptResult.forcedKill
+      });
+      lastResult = {
+        code: attemptResult.code,
+        timedOut: attemptResult.timedOut,
+        elapsedMs: attemptResult.elapsedMs,
+        signal: attemptResult.signal,
+        spawnErrorCode: attemptResult.spawnErrorCode,
+        forcedKill: attemptResult.forcedKill
+      };
+
+      if (attemptResult.ok) {
+        return {
+          ok: true,
+          code: attemptResult.code,
+          stdout,
+          stderr,
+          timedOut: false,
+          elapsedMs: attempts.reduce((sum, item) => sum + item.elapsedMs, 0),
+          attemptCount: attempts.length,
+          attempts,
+          parsedUsage: parseStructuredUsage(stdout)
+        };
+      }
+
+      const retryableSpawnError = Boolean(
+        attemptResult.spawnErrorCode && TRANSIENT_SPAWN_ERROR_CODES.has(attemptResult.spawnErrorCode)
+      );
+      const retryableCodexNonZero =
+        provider === "codex" && !attemptResult.timedOut && !attemptResult.spawnErrorCode && attemptResult.code !== 0;
+      const retryable = retryableSpawnError || retryableCodexNonZero;
+      if (!retryable || attempt >= maxAttempts) {
+        break;
+      }
+      await sleep(retryBackoffMs * attempt);
+    }
+
+    return {
+      ok: false,
+      code: lastResult?.code ?? null,
+      stdout,
+      stderr,
+      timedOut: lastResult?.timedOut ?? false,
+      elapsedMs: attempts.reduce((sum, item) => sum + item.elapsedMs, 0),
+      attemptCount: attempts.length,
+      attempts,
+      failureType: classifyFailure(lastResult?.timedOut ?? false, lastResult?.spawnErrorCode, lastResult?.code ?? null),
+      parsedUsage: parseStructuredUsage(stdout)
+    };
+  } finally {
+    await injection.cleanup();
+  }
+}
+
+const SKILLS_DIR_NAME = "skills";
+const CLAUDE_SKILLS_DIR = ".claude/skills";
+const SKILL_MD = "SKILL.md";
+
+type SkillInjectionContext = {
+  additionalArgs: string[];
+  warning?: string;
+  cleanup: () => Promise<void>;
+};
+
+async function prepareSkillInjection(
+  provider: "claude_code" | "codex" | undefined,
+  env: NodeJS.ProcessEnv
+): Promise<SkillInjectionContext> {
+  if (!provider) {
+    return noSkillInjection();
+  }
+
+  const skillsSource = await resolveSkillsSourceDir();
+  if (!skillsSource) {
+    return {
+      ...noSkillInjection(),
+      warning: "[bopohq] skills injection skipped: no skills directory found."
+    };
+  }
+
+  if (provider === "codex") {
+    try {
+      await ensureCodexSkillsInjected(skillsSource, env);
+      return noSkillInjection();
+    } catch (error) {
+      return {
+        ...noSkillInjection(),
+        warning: `[bopohq] skills injection failed for codex: ${String(error)}`
+      };
+    }
+  }
+
+  try {
+    const tempSkillsRoot = await buildClaudeSkillsAddDir(skillsSource);
+    return {
+      additionalArgs: ["--add-dir", tempSkillsRoot],
+      cleanup: async () => {
+        await rm(tempSkillsRoot, { recursive: true, force: true });
+      }
+    };
+  } catch (error) {
+    return {
+      ...noSkillInjection(),
+      warning: `[bopohq] skills injection failed for claude_code: ${String(error)}`
+    };
+  }
+}
+
+function noSkillInjection(): SkillInjectionContext {
+  return {
+    additionalArgs: [],
+    cleanup: async () => {}
+  };
+}
+
+const TRANSIENT_SPAWN_ERROR_CODES = new Set(["EAGAIN", "EMFILE", "ENFILE", "ETXTBSY", "EBUSY"]);
+const FORCE_KILL_AFTER_MS = 2_000;
+
+async function executeSinglePromptAttempt(
+  command: string,
+  args: string[],
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+  timeoutMs: number
+) {
+  const startedAt = Date.now();
+  return new Promise<{
+    ok: boolean;
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    elapsedMs: number;
+    signal: NodeJS.Signals | null;
+    spawnErrorCode?: string;
+    forcedKill: boolean;
+  }>((resolve) => {
+    const child = spawn(command, args, {
+      cwd,
+      env,
+      shell: false
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let resolved = false;
+    let timedOut = false;
+    let forcedKill = false;
+    let timeoutKillTimer: NodeJS.Timeout | undefined;
+    const timeout = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+      timeoutKillTimer = setTimeout(() => {
+        if (!resolved) {
+          forcedKill = true;
+          child.kill("SIGKILL");
+        }
+      }, FORCE_KILL_AFTER_MS);
+    }, timeoutMs);
+
+    child.stdout.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+
+    child.on("close", (code, signal) => {
+      if (resolved) {
+        return;
+      }
+      resolved = true;
+      clearTimeout(timeout);
+      if (timeoutKillTimer) {
+        clearTimeout(timeoutKillTimer);
+      }
+      resolve({
+        ok: code === 0 && !timedOut,
+        code,
+        stdout,
+        stderr,
+        timedOut,
+        elapsedMs: Date.now() - startedAt,
+        signal,
+        forcedKill
+      });
+    });
+
+    child.on("error", (error) => {
+      if (resolved) {
+        return;
+      }
+      resolved = true;
+      clearTimeout(timeout);
+      if (timeoutKillTimer) {
+        clearTimeout(timeoutKillTimer);
+      }
+      const errorWithCode = error as NodeJS.ErrnoException;
+      resolve({
+        ok: false,
+        code: null,
+        stdout,
+        stderr: `${stderr}\n${String(error)}`.trim(),
+        timedOut,
+        elapsedMs: Date.now() - startedAt,
+        signal: null,
+        spawnErrorCode: errorWithCode.code,
+        forcedKill
+      });
+    });
+  });
+}
+
+function classifyFailure(timedOut: boolean, spawnErrorCode: string | undefined, code: number | null) {
+  if (timedOut) {
+    return "timeout" as const;
+  }
+  if (spawnErrorCode) {
+    return "spawn_error" as const;
+  }
+  if (code !== 0) {
+    return "nonzero_exit" as const;
+  }
+  return undefined;
+}
+
+function sleep(ms: number) {
+  return new Promise<void>((resolve) => setTimeout(resolve, ms));
+}
+
+export async function checkRuntimeCommandHealth(
+  command: string,
+  options?: { cwd?: string; timeoutMs?: number }
+): Promise<RuntimeCommandHealth> {
+  const startedAt = Date.now();
+  return new Promise((resolve) => {
+    const child = spawn(command, ["--version"], {
+      cwd: options?.cwd ?? process.cwd(),
+      env: process.env,
+      shell: false
+    });
+
+    let resolved = false;
+    const timeout = setTimeout(() => {
+      if (resolved) {
+        return;
+      }
+      resolved = true;
+      child.kill("SIGTERM");
+      resolve({
+        command,
+        available: false,
+        exitCode: null,
+        elapsedMs: Date.now() - startedAt,
+        error: "Command health check timed out."
+      });
+    }, options?.timeoutMs ?? 5_000);
+
+    child.on("close", (code) => {
+      if (resolved) {
+        return;
+      }
+      resolved = true;
+      clearTimeout(timeout);
+      resolve({
+        command,
+        available: true,
+        exitCode: code,
+        elapsedMs: Date.now() - startedAt
+      });
+    });
+
+    child.on("error", (error) => {
+      if (resolved) {
+        return;
+      }
+      resolved = true;
+      clearTimeout(timeout);
+      resolve({
+        command,
+        available: false,
+        exitCode: null,
+        elapsedMs: Date.now() - startedAt,
+        error: String(error)
+      });
+    });
+  });
+}
+
+async function resolveSkillsSourceDir() {
+  const moduleDir = dirname(fileURLToPath(import.meta.url));
+  const candidates = [resolve(moduleDir, "../../../skills"), resolve(process.cwd(), "skills")];
+  for (const candidate of candidates) {
+    if (await isDirectory(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+async function ensureCodexSkillsInjected(skillsSourceDir: string, env: NodeJS.ProcessEnv) {
+  const codexHome = resolveCodexHome(env);
+  const targetRoot = join(codexHome, SKILLS_DIR_NAME);
+  await mkdir(targetRoot, { recursive: true });
+
+  const entries = await readdir(skillsSourceDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const source = join(skillsSourceDir, entry.name);
+    if (!(await hasSkillManifest(source))) {
+      continue;
+    }
+    const target = join(targetRoot, entry.name);
+    const existing = await lstat(target).catch(() => null);
+    if (existing) {
+      continue;
+    }
+    await symlink(source, target);
+  }
+}
+
+function resolveCodexHome(env: NodeJS.ProcessEnv) {
+  const configured = env.CODEX_HOME?.trim();
+  if (configured) {
+    return configured;
+  }
+  return join(homedir(), ".codex");
+}
+
+async function buildClaudeSkillsAddDir(skillsSourceDir: string) {
+  const tempRoot = await mkdtemp(join(tmpdir(), "bopohq-skills-"));
+  const skillsTargetDir = join(tempRoot, CLAUDE_SKILLS_DIR);
+  await mkdir(skillsTargetDir, { recursive: true });
+
+  const entries = await readdir(skillsSourceDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const source = join(skillsSourceDir, entry.name);
+    if (!(await hasSkillManifest(source))) {
+      continue;
+    }
+    await symlink(source, join(skillsTargetDir, entry.name));
+  }
+
+  return tempRoot;
+}
+
+async function hasSkillManifest(skillDir: string) {
+  return fileExists(join(skillDir, SKILL_MD));
+}
+
+async function isDirectory(path: string) {
+  const stats = await lstat(path).catch(() => null);
+  return stats?.isDirectory() ?? false;
+}
+
+async function fileExists(path: string) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function parseStructuredUsage(stdout: string) {
+  const lines = stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean);
+
+  for (let index = lines.length - 1; index >= 0; index -= 1) {
+    const candidate = lines[index];
+    if (candidate?.startsWith("{") && candidate.endsWith("}")) {
+      const parsed = tryParseUsage(candidate);
+      if (parsed) {
+        return parsed;
+      }
+    }
+
+    const fragments = candidate?.match(/\{[^{}]+\}/g) ?? [];
+    for (let fragmentIndex = fragments.length - 1; fragmentIndex >= 0; fragmentIndex -= 1) {
+      const parsed = tryParseUsage(fragments[fragmentIndex] ?? "");
+      if (parsed) {
+        return parsed;
+      }
+    }
+  }
+
+  return undefined;
+}
+
+function tryParseUsage(candidate: string) {
+  try {
+    const parsed = JSON.parse(candidate) as Record<string, unknown>;
+    const tokenInput = toNumber(parsed.tokenInput);
+    const tokenOutput = toNumber(parsed.tokenOutput);
+    const usdCost = toNumber(parsed.usdCost);
+    const summary = typeof parsed.summary === "string" ? parsed.summary : undefined;
+    const executionMode: "local_work" | "control_plane" | undefined =
+      parsed.executionMode === "local_work" || parsed.executionMode === "control_plane"
+        ? parsed.executionMode
+        : undefined;
+    const gatedControlPlaneReasons = Array.isArray(parsed.gatedControlPlaneReasons)
+      ? parsed.gatedControlPlaneReasons.map((item) => String(item))
+      : undefined;
+    if (isPromptTemplateUsage(summary, tokenInput, tokenOutput, usdCost, executionMode, gatedControlPlaneReasons)) {
+      return undefined;
+    }
+    if (
+      tokenInput === undefined &&
+      tokenOutput === undefined &&
+      usdCost === undefined &&
+      !summary &&
+      !executionMode &&
+      !gatedControlPlaneReasons
+    ) {
+      return undefined;
+    }
+    return { tokenInput, tokenOutput, usdCost, summary, executionMode, gatedControlPlaneReasons };
+  } catch {
+    return undefined;
+  }
+}
+
+function isPromptTemplateUsage(
+  summary: string | undefined,
+  tokenInput: number | undefined,
+  tokenOutput: number | undefined,
+  usdCost: number | undefined,
+  executionMode: "local_work" | "control_plane" | undefined,
+  gatedControlPlaneReasons: string[] | undefined
+) {
+  return (
+    summary === "..." &&
+    tokenInput === 123 &&
+    tokenOutput === 456 &&
+    usdCost === 0.123456 &&
+    executionMode === "local_work" &&
+    Array.isArray(gatedControlPlaneReasons) &&
+    gatedControlPlaneReasons.length === 1 &&
+    gatedControlPlaneReasons[0] === "..."
+  );
+}
+
+function toNumber(value: unknown) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string") {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) {
+      return parsed;
+    }
+  }
+  return undefined;
+}

package/src/types.ts

@@ -0,0 +1,92 @@
+import type { ProviderType } from "bopodev-contracts";
+
+export type AgentProviderType = ProviderType;
+
+export interface AgentWorkItem {
+  issueId: string;
+  projectId: string;
+  projectName?: string | null;
+  title: string;
+  body?: string | null;
+  status?: string;
+  priority?: string;
+  labels?: string[];
+  tags?: string[];
+}
+
+export interface AgentState {
+  sessionId?: string;
+  cwd?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface HeartbeatContext {
+  companyId: string;
+  agentId: string;
+  providerType: AgentProviderType;
+  heartbeatRunId: string;
+  company: {
+    name: string;
+    mission?: string | null;
+  };
+  agent: {
+    name: string;
+    role: string;
+    managerAgentId?: string | null;
+  };
+  workItems: AgentWorkItem[];
+  goalContext?: {
+    companyGoals: string[];
+    projectGoals: string[];
+    agentGoals: string[];
+  };
+  state: AgentState;
+  runtime?: AgentRuntimeConfig;
+}
+
+export interface AdapterExecutionResult {
+  status: "ok" | "skipped" | "failed";
+  summary: string;
+  tokenInput: number;
+  tokenOutput: number;
+  usdCost: number;
+  nextState?: AgentState;
+  trace?: AdapterTrace;
+}
+
+export interface AgentAdapter {
+  providerType: AgentProviderType;
+  execute(context: HeartbeatContext): Promise<AdapterExecutionResult>;
+}
+
+export interface AgentRuntimeConfig {
+  command?: string;
+  args?: string[];
+  cwd?: string;
+  timeoutMs?: number;
+  retryCount?: number;
+  retryBackoffMs?: number;
+  env?: Record<string, string>;
+}
+
+export interface AdapterTrace {
+  command?: string;
+  exitCode?: number | null;
+  elapsedMs?: number;
+  timedOut?: boolean;
+  failureType?: string;
+  attemptCount?: number;
+  attempts?: Array<{
+    attempt: number;
+    code: number | null;
+    timedOut: boolean;
+    elapsedMs: number;
+    signal: NodeJS.Signals | null;
+    spawnErrorCode?: string;
+    forcedKill: boolean;
+  }>;
+  stdoutPreview?: string;
+  stderrPreview?: string;
+  executionMode?: "local_work" | "control_plane";
+  gatedControlPlaneReasons?: string[];
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "declaration": true,
+    "emitDeclarationOnly": true
+  },
+  "include": ["src"]
+}