bopodev-agent-sdk 0.1.1

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "bopodev-agent-sdk",
+  "version": "0.1.1",
+  "license": "MIT",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "dependencies": {
+    "bopodev-contracts": "0.1.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json --emitDeclarationOnly",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/adapters.ts

@@ -0,0 +1,324 @@
+import type { AdapterExecutionResult, AgentAdapter, HeartbeatContext } from "./types";
+import { executeAgentRuntime, executePromptRuntime } from "./runtime";
+
+function summarizeWork(context: HeartbeatContext) {
+  if (context.workItems.length === 0) {
+    return "No assigned work found.";
+  }
+  return `Processed ${context.workItems.length} assigned issue(s).`;
+}
+
+export class ClaudeCodeAdapter implements AgentAdapter {
+  providerType = "claude_code" as const;
+
+  async execute(context: HeartbeatContext): Promise<AdapterExecutionResult> {
+    if (context.workItems.length === 0) {
+      return createSkippedResult("Claude Code", "claude_code", context);
+    }
+    return runProviderWork(context, "claude_code", {
+      inputRate: 0.000002,
+      outputRate: 0.00001
+    });
+  }
+}
+
+export class CodexAdapter implements AgentAdapter {
+  providerType = "codex" as const;
+
+  async execute(context: HeartbeatContext): Promise<AdapterExecutionResult> {
+    if (context.workItems.length === 0) {
+      return createSkippedResult("Codex", "codex", context);
+    }
+    return runProviderWork(context, "codex", {
+      inputRate: 0.0000015,
+      outputRate: 0.000008
+    });
+  }
+}
+
+export class GenericHeartbeatAdapter implements AgentAdapter {
+  constructor(public providerType: "http" | "shell") {}
+
+  async execute(context: HeartbeatContext): Promise<AdapterExecutionResult> {
+    if (context.workItems.length === 0) {
+      return createSkippedResult(this.providerType, this.providerType, context);
+    }
+    if (!context.runtime?.command) {
+      return {
+        status: "failed",
+        summary: `${this.providerType} adapter is missing a runtime command.`,
+        tokenInput: 0,
+        tokenOutput: 0,
+        usdCost: 0,
+        nextState: context.state
+      };
+    }
+
+    const credentialState = resolveControlPlaneCredentialState(context);
+    const prompt = createPrompt(context, credentialState);
+    const runtime = await executePromptRuntime(context.runtime.command, prompt, context.runtime);
+    const executionMode = runtime.parsedUsage?.executionMode ?? defaultExecutionMode(credentialState);
+    const gatedControlPlaneReasons = runtime.parsedUsage?.gatedControlPlaneReasons ?? credentialState.missingReasons;
+    if (runtime.ok) {
+      return {
+        status: "ok",
+        summary: withExecutionDiagnostics(
+          runtime.parsedUsage?.summary ?? `${this.providerType} runtime finished in ${runtime.elapsedMs}ms.`,
+          executionMode,
+          gatedControlPlaneReasons
+        ),
+        tokenInput: runtime.parsedUsage?.tokenInput ?? 0,
+        tokenOutput: runtime.parsedUsage?.tokenOutput ?? 0,
+        usdCost: runtime.parsedUsage?.usdCost ?? 0,
+        trace: {
+          command: context.runtime.command,
+          exitCode: runtime.code,
+          elapsedMs: runtime.elapsedMs,
+          timedOut: runtime.timedOut,
+          failureType: runtime.failureType,
+          attemptCount: runtime.attemptCount,
+          attempts: runtime.attempts,
+          stdoutPreview: toPreview(runtime.stdout),
+          stderrPreview: toPreview(runtime.stderr),
+          executionMode,
+          gatedControlPlaneReasons
+        },
+        nextState: withProviderMetadata(context, this.providerType, runtime.elapsedMs, runtime.code)
+      };
+    }
+
+    return {
+      status: "failed",
+      summary: withExecutionDiagnostics(
+        `${this.providerType} runtime failed: ${runtime.stderr || "unknown error"}`,
+        executionMode,
+        gatedControlPlaneReasons
+      ),
+      tokenInput: 0,
+      tokenOutput: 0,
+      usdCost: 0,
+      trace: {
+        command: context.runtime.command,
+        exitCode: runtime.code,
+        elapsedMs: runtime.elapsedMs,
+        timedOut: runtime.timedOut,
+        failureType: runtime.failureType,
+        attemptCount: runtime.attemptCount,
+        attempts: runtime.attempts,
+        stdoutPreview: toPreview(runtime.stdout),
+        stderrPreview: toPreview(runtime.stderr),
+        executionMode,
+        gatedControlPlaneReasons
+      },
+      nextState: context.state
+    };
+  }
+}
+
+function createSkippedResult(providerLabel: string, providerKey: string, context: HeartbeatContext): AdapterExecutionResult {
+  return {
+    status: "skipped",
+    summary: `${providerLabel} adapter: ${summarizeWork(context)}`,
+    tokenInput: 0,
+    tokenOutput: 0,
+    usdCost: 0,
+    nextState: withProviderMetadata(context, providerKey)
+  };
+}
+
+async function runProviderWork(
+  context: HeartbeatContext,
+  provider: "claude_code" | "codex",
+  pricing: { inputRate: number; outputRate: number }
+): Promise<AdapterExecutionResult> {
+  const credentialState = resolveControlPlaneCredentialState(context);
+  const prompt = createPrompt(context, credentialState);
+  const runtime = await executeAgentRuntime(provider, prompt, context.runtime);
+  const executionMode = runtime.parsedUsage?.executionMode ?? defaultExecutionMode(credentialState);
+  const gatedControlPlaneReasons = runtime.parsedUsage?.gatedControlPlaneReasons ?? credentialState.missingReasons;
+  if (runtime.ok) {
+    const fallbackOutputTokens = Math.max(Math.round(runtime.stdout.length / 4), 80);
+    const fallbackInputTokens = Math.max(Math.round(prompt.length / 4), 120);
+    const tokenInput = runtime.parsedUsage?.tokenInput ?? fallbackInputTokens;
+    const tokenOutput = runtime.parsedUsage?.tokenOutput ?? fallbackOutputTokens;
+    const usdCost =
+      runtime.parsedUsage?.usdCost ??
+      Number((tokenInput * pricing.inputRate + tokenOutput * pricing.outputRate).toFixed(6));
+    const summary = withExecutionDiagnostics(
+      runtime.parsedUsage?.summary ?? `${provider} runtime finished in ${runtime.elapsedMs}ms.`,
+      executionMode,
+      gatedControlPlaneReasons
+    );
+
+    return {
+      status: "ok",
+      summary,
+      tokenInput,
+      tokenOutput,
+      usdCost,
+      trace: {
+        command: context.runtime?.command ?? provider,
+        exitCode: runtime.code,
+        elapsedMs: runtime.elapsedMs,
+        timedOut: runtime.timedOut,
+        failureType: runtime.failureType,
+        attemptCount: runtime.attemptCount,
+        attempts: runtime.attempts,
+        stdoutPreview: toPreview(runtime.stdout),
+        stderrPreview: toPreview(runtime.stderr),
+        executionMode,
+        gatedControlPlaneReasons
+      },
+      nextState: withProviderMetadata(context, provider, runtime.elapsedMs, runtime.code)
+    };
+  }
+  return {
+    status: "failed",
+    summary: withExecutionDiagnostics(
+      `${provider} runtime failed: ${runtime.stderr || "unknown error"}`,
+      executionMode,
+      gatedControlPlaneReasons
+    ),
+    tokenInput: 0,
+    tokenOutput: 0,
+    usdCost: 0,
+    trace: {
+      command: context.runtime?.command ?? provider,
+      exitCode: runtime.code,
+      elapsedMs: runtime.elapsedMs,
+      timedOut: runtime.timedOut,
+      failureType: runtime.failureType,
+      attemptCount: runtime.attemptCount,
+      attempts: runtime.attempts,
+      stdoutPreview: toPreview(runtime.stdout),
+      stderrPreview: toPreview(runtime.stderr),
+      executionMode,
+      gatedControlPlaneReasons
+    },
+    nextState: context.state
+  };
+}
+
+function createPrompt(context: HeartbeatContext, credentialState = resolveControlPlaneCredentialState(context)) {
+  const companyGoals = context.goalContext?.companyGoals.length
+    ? context.goalContext.companyGoals.map((goal) => `- ${goal}`).join("\n")
+    : "- No active company goals";
+  const projectGoals = context.goalContext?.projectGoals.length
+    ? context.goalContext.projectGoals.map((goal) => `- ${goal}`).join("\n")
+    : "- No active project goals";
+  const agentGoals = context.goalContext?.agentGoals.length
+    ? context.goalContext.agentGoals.map((goal) => `- ${goal}`).join("\n")
+    : "- No active agent goals";
+  const workItems = context.workItems.length
+    ? context.workItems
+        .map((item) =>
+          [
+            `- [${item.issueId}] ${item.title}`,
+            `  Project: ${item.projectName ?? item.projectId}`,
+            item.status ? `  Status: ${item.status}` : null,
+            item.priority ? `  Priority: ${item.priority}` : null,
+            item.body ? `  Body: ${item.body}` : null,
+            item.labels?.length ? `  Labels: ${item.labels.join(", ")}` : null,
+            item.tags?.length ? `  Tags: ${item.tags.join(", ")}` : null
+          ]
+            .filter(Boolean)
+            .join("\n")
+        )
+        .join("\n")
+    : "- No assigned work";
+
+  const executionDirectives = [
+    "Execution directives:",
+    "- You are running inside a BopoHQ heartbeat for local repository work.",
+    "- Use injected skills from the local Codex/agent skills directory when relevant.",
+    "- Prefer completing assigned issue work in this repository over control-plane orchestration tasks.",
+    "- Only use BopoHQ control-plane APIs/skills when BOPOHQ_API_URL and BOPOHQ_API_KEY are present.",
+    "- If those credentials are missing, do not attempt control-plane calls; continue with local issue execution and report constraints briefly.",
+    "- Keep command usage minimal and task-focused; avoid broad repository scans unless strictly required for the assigned issue.",
+    "- If any command fails, avoid further exploratory commands and still return the required final JSON summary."
+  ].join("\n");
+  const credentialSnapshot = [
+    "Control-plane credential snapshot:",
+    `- BopoHQ credentials: ${credentialState.bopohqEnabled ? "present" : "missing"}`,
+    ...credentialState.missingReasons.map((reason) => `- Gate: ${reason}`)
+  ].join("\n");
+
+  return `You are ${context.agent.name} (${context.agent.role}), agent ${context.agentId}.
+Heartbeat run ${context.heartbeatRunId}.
+
+Company:
+- Name: ${context.company.name}
+- Mission: ${context.company.mission ?? "No mission set"}
+
+Goal context:
+Company goals:
+${companyGoals}
+Project goals:
+${projectGoals}
+Agent goals:
+${agentGoals}
+
+Assigned issues:
+${workItems}
+
+${executionDirectives}
+${credentialSnapshot}
+
+At the end of your response, include exactly one JSON object on a single line:
+{"summary":"...","tokenInput":123,"tokenOutput":456,"usdCost":0.123456,"executionMode":"local_work","gatedControlPlaneReasons":["..."]}
+`;
+}
+
+function resolveControlPlaneCredentialState(context: HeartbeatContext) {
+  const env = {
+    ...process.env,
+    ...(context.runtime?.env ?? {})
+  };
+  const bopohqEnabled = Boolean(env.BOPOHQ_API_URL && env.BOPOHQ_API_KEY);
+  const missingReasons: string[] = [];
+  if (!bopohqEnabled) {
+    missingReasons.push("bopohq credentials missing (BOPOHQ_API_URL and/or BOPOHQ_API_KEY)");
+  }
+  return {
+    bopohqEnabled,
+    missingReasons
+  };
+}
+
+function defaultExecutionMode(credentialState: {
+  bopohqEnabled: boolean;
+}) {
+  return credentialState.bopohqEnabled ? "control_plane" : "local_work";
+}
+
+function withExecutionDiagnostics(summary: string, executionMode: "local_work" | "control_plane", reasons: string[]) {
+  if (reasons.length === 0) {
+    return `${summary} [mode=${executionMode}]`;
+  }
+  return `${summary} [mode=${executionMode}; gated=${reasons.join(" | ")}]`;
+}
+
+function withProviderMetadata(
+  context: HeartbeatContext,
+  provider: string,
+  lastRuntimeMs?: number,
+  lastExitCode?: number | null
+) {
+  return {
+    ...context.state,
+    metadata: {
+      ...(context.state.metadata ?? {}),
+      lastProvider: provider,
+      lastHeartbeatRunId: context.heartbeatRunId,
+      ...(lastRuntimeMs === undefined ? {} : { lastRuntimeMs }),
+      ...(lastExitCode === undefined ? {} : { lastExitCode })
+    }
+  };
+}
+
+function toPreview(value: string, max = 1600) {
+  if (value.length <= max) {
+    return value;
+  }
+  return `${value.slice(0, max)}\n...[truncated]`;
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./adapters";
+export * from "./registry";
+export * from "./runtime";
+export * from "./types";

package/src/registry.ts

@@ -0,0 +1,13 @@
+import { ClaudeCodeAdapter, CodexAdapter, GenericHeartbeatAdapter } from "./adapters";
+import type { AgentAdapter, AgentProviderType } from "./types";
+
+const adapters: Record<AgentProviderType, AgentAdapter> = {
+  claude_code: new ClaudeCodeAdapter(),
+  codex: new CodexAdapter(),
+  http: new GenericHeartbeatAdapter("http"),
+  shell: new GenericHeartbeatAdapter("shell")
+};
+
+export function resolveAdapter(providerType: AgentProviderType) {
+  return adapters[providerType];
+}