bopodev-agent-sdk 0.1.26 → 0.1.27

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
 
-> bopodev-agent-sdk@0.1.26 build /Users/danielkrusenstrahle/Documents/Projects/Monorepo/bopohq/packages/agent-sdk
+> bopodev-agent-sdk@0.1.27 build /Users/danielkrusenstrahle/Documents/Projects/Monorepo/bopohq/packages/agent-sdk
 > tsc -p tsconfig.json --emitDeclarationOnly
 

package/.turbo/turbo-typecheck.log

@@ -1,4 +1,4 @@
 
-> bopodev-agent-sdk@0.1.24 typecheck /Users/danielkrusenstrahle/Documents/Projects/Monorepo/bopohq/packages/agent-sdk
+> bopodev-agent-sdk@0.1.26 typecheck /Users/danielkrusenstrahle/Documents/Projects/Monorepo/bopohq/packages/agent-sdk
 > tsc -p tsconfig.json --noEmit
 

package/README.md

@@ -0,0 +1,27 @@
+# `packages/agent-sdk`
+
+Runtime orchestration SDK for adapter resolution, execution integration, and runtime health checks.
+
+## Responsibilities
+
+- Resolve and register adapter modules.
+- Provide shared execution/runtime helpers used by API heartbeat workflows.
+- Expose runtime command health checks used at API startup and health endpoints.
+
+## Usage
+
+Primary consumers:
+
+- `apps/api` heartbeat and startup paths.
+- `packages/adapters/*` through adapter module contracts.
+
+## Commands
+
+- `pnpm --filter bopodev-agent-sdk build`
+- `pnpm --filter bopodev-agent-sdk typecheck`
+
+## Related Docs
+
+- `docs/adapters/overview.md`
+- `docs/adapter-authoring.md`
+- `docs/developer/architecture.md`

package/dist/adapters/codex/src/server/quota.d.ts

@@ -0,0 +1,2 @@
+import type { AgentRuntimeConfig, AdapterQuotaProbeResult } from "../../../../agent-sdk/src/types";
+export declare function probeQuota(runtime?: AgentRuntimeConfig): Promise<AdapterQuotaProbeResult>;

package/dist/agent-sdk/src/quota.d.ts

@@ -0,0 +1,4 @@
+import type { AgentProviderType, AdapterQuotaProbeResult, AgentRuntimeConfig } from "./types";
+export declare function createUnsupportedQuotaProbeResult(providerType: AgentProviderType, message: string): AdapterQuotaProbeResult;
+export declare function createAuthRequiredQuotaProbeResult(providerType: AgentProviderType, message: string): AdapterQuotaProbeResult;
+export declare function resolveMergedEnv(runtime?: AgentRuntimeConfig): NodeJS.ProcessEnv;

package/dist/agent-sdk/src/types.d.ts

@@ -19,6 +19,8 @@ export interface AgentWorkItem {
         fileSizeBytes: number;
         relativePath: string;
         absolutePath: string;
+        /** API-relative path, e.g. `/issues/{issueId}/attachments/{id}/download` */
+        downloadPath?: string;
     }>;
 }
 export interface AgentState {
@@ -36,11 +38,19 @@ export interface AgentMemoryContext {
     durableFacts: string[];
     dailyNotes: string[];
 }
+export type HeartbeatPromptMode = "full" | "compact";
 export interface HeartbeatContext {
     companyId: string;
     agentId: string;
     providerType: AgentProviderType;
     heartbeatRunId: string;
+    /** Controls how much issue/memory text is inlined in the heartbeat prompt. Default when omitted: full. */
+    promptMode?: HeartbeatPromptMode;
+    /**
+     * When true, emit a minimal idle prompt (no assigned work). Set by the API when
+     * `BOPO_HEARTBEAT_IDLE_POLICY=micro_prompt` and there are no work items.
+     */
+    idleMicroPrompt?: boolean;
     company: {
         name: string;
         mission?: string | null;

package/dist/contracts/src/index.d.ts

@@ -168,6 +168,72 @@ export declare const IssueAttachmentSchema: z.ZodObject<{
     createdAt: z.ZodString;
 }, z.core.$strip>;
 export type IssueAttachment = z.infer<typeof IssueAttachmentSchema>;
+/** Single-issue GET: core issue fields plus attachment metadata and API download paths. */
+export declare const IssueAttachmentWithDownloadSchema: z.ZodObject<{
+    id: z.ZodString;
+    companyId: z.ZodString;
+    issueId: z.ZodString;
+    projectId: z.ZodString;
+    fileName: z.ZodString;
+    mimeType: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    fileSizeBytes: z.ZodNumber;
+    relativePath: z.ZodString;
+    uploadedByActorType: z.ZodEnum<{
+        human: "human";
+        agent: "agent";
+        system: "system";
+    }>;
+    uploadedByActorId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    createdAt: z.ZodString;
+    downloadPath: z.ZodString;
+}, z.core.$strip>;
+export declare const IssueDetailSchema: z.ZodObject<{
+    id: z.ZodString;
+    companyId: z.ZodString;
+    projectId: z.ZodString;
+    parentIssueId: z.ZodNullable<z.ZodString>;
+    title: z.ZodString;
+    body: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    status: z.ZodEnum<{
+        blocked: "blocked";
+        todo: "todo";
+        in_progress: "in_progress";
+        in_review: "in_review";
+        done: "done";
+        canceled: "canceled";
+    }>;
+    priority: z.ZodEnum<{
+        none: "none";
+        low: "low";
+        medium: "medium";
+        high: "high";
+        urgent: "urgent";
+    }>;
+    assigneeAgentId: z.ZodNullable<z.ZodString>;
+    labels: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    attachments: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        companyId: z.ZodString;
+        issueId: z.ZodString;
+        projectId: z.ZodString;
+        fileName: z.ZodString;
+        mimeType: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        fileSizeBytes: z.ZodNumber;
+        relativePath: z.ZodString;
+        uploadedByActorType: z.ZodEnum<{
+            human: "human";
+            agent: "agent";
+            system: "system";
+        }>;
+        uploadedByActorId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        createdAt: z.ZodString;
+        downloadPath: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type IssueDetail = z.infer<typeof IssueDetailSchema>;
 export declare const IssueCommentRecipientSchema: z.ZodObject<{
     recipientType: z.ZodEnum<{
         agent: "agent";
@@ -1618,6 +1684,9 @@ export declare const ControlPlaneRuntimeEnvSchema: z.ZodObject<{
     BOPODEV_WAKE_REASON: z.ZodOptional<z.ZodString>;
     BOPODEV_WAKE_COMMENT_ID: z.ZodOptional<z.ZodString>;
     BOPODEV_LINKED_ISSUE_IDS: z.ZodOptional<z.ZodString>;
+    BOPODEV_COMPANY_WORKSPACE_ROOT: z.ZodOptional<z.ZodString>;
+    BOPODEV_AGENT_HOME: z.ZodOptional<z.ZodString>;
+    BOPODEV_AGENT_OPERATING_DIR: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ControlPlaneRuntimeEnv = z.infer<typeof ControlPlaneRuntimeEnvSchema>;
 export declare const ExecutionOutcomeKindSchema: z.ZodEnum<{
@@ -1732,6 +1801,7 @@ export declare const RunArtifactSchema: z.ZodObject<{
     label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     relativePath: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     absolutePath: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    verifiedOnDisk: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type RunArtifact = z.infer<typeof RunArtifactSchema>;
 export declare const RunCostSummarySchema: z.ZodObject<{
@@ -1808,6 +1878,7 @@ export declare const RunCompletionReportSchema: z.ZodObject<{
         label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         relativePath: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         absolutePath: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        verifiedOnDisk: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>>;
     blockers: z.ZodDefault<z.ZodArray<z.ZodString>>;
     nextAction: z.ZodString;
@@ -4539,6 +4610,7 @@ export declare const HeartbeatRunDetailSchema: z.ZodObject<{
                 label: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                 relativePath: z.ZodOptional<z.ZodNullable<z.ZodString>>;
                 absolutePath: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+                verifiedOnDisk: z.ZodOptional<z.ZodBoolean>;
             }, z.core.$strip>>>;
             blockers: z.ZodDefault<z.ZodArray<z.ZodString>>;
             nextAction: z.ZodString;

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "bopodev-agent-sdk",
-  "version": "0.1.26",
+  "version": "0.1.27",
   "license": "MIT",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
   "dependencies": {
-    "bopodev-contracts": "0.1.26"
+    "bopodev-contracts": "0.1.27"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json --emitDeclarationOnly",

package/src/adapters.ts

@@ -8,7 +8,8 @@ import type {
   AgentAdapter,
   AgentProviderType,
   AgentRuntimeConfig,
-  HeartbeatContext
+  HeartbeatContext,
+  HeartbeatPromptMode
 } from "./types";
 import { ExecutionOutcomeSchema, type ExecutionOutcome } from "bopodev-contracts";
 import {
@@ -2616,8 +2617,66 @@ export function toEnvironmentStatus(checks: AdapterEnvironmentCheck[]): "pass" |
   return "pass";
 }
 
+function resolveHeartbeatPromptModeForPrompt(context: HeartbeatContext): HeartbeatPromptMode {
+  return context.promptMode === "compact" ? "compact" : "full";
+}
+
+/** Max chars per memory section (tacit notes, durable facts block, daily notes block). Env overrides; compact defaults to 8000. */
+function resolveMemorySectionMaxChars(mode: HeartbeatPromptMode): number | null {
+  const raw = process.env.BOPO_HEARTBEAT_PROMPT_MEMORY_MAX_CHARS?.trim();
+  if (raw) {
+    const n = Number.parseInt(raw, 10);
+    if (Number.isFinite(n) && n > 0) {
+      return n;
+    }
+  }
+  if (mode === "compact") {
+    return 8000;
+  }
+  return null;
+}
+
+function clipPromptText(text: string, max: number | null): string {
+  if (!max || text.length <= max) {
+    return text;
+  }
+  return `${text.slice(0, max)}\n…(truncated for prompt size)`;
+}
+
+const HEARTBEAT_JSON_SCHEMA_FOOTER = `At the end of your response, output exactly one JSON object on a single line and nothing else. Use this exact schema:
+{"employee_comment":"markdown update to the manager","results":["short concrete outcome"],"errors":[],"artifacts":[{"kind":"file","path":"relative/path"}]}`;
+
+function buildIdleMicroPrompt(context: HeartbeatContext): string {
+  const bootstrapPrompt = context.runtime?.bootstrapPrompt?.trim();
+  return `${bootstrapPrompt ? `${bootstrapPrompt}\n\n` : ""}Idle heartbeat (micro prompt): agent ${context.agentId} (${context.agent.name}) has no assigned issues this run. Summarize readiness in \`employee_comment\`; leave \`results\` empty unless you completed verifiable work. Use \`BOPODEV_*\` for control-plane API calls when needed.
+
+${HEARTBEAT_JSON_SCHEMA_FOOTER}
+`;
+}
+
+function formatAttachmentLine(
+  attachment: NonNullable<HeartbeatContext["workItems"][number]["attachments"]>[number],
+  mode: HeartbeatPromptMode,
+  apiBase: string
+): string {
+  const base = apiBase.replace(/\/$/, "");
+  const apiUrl = attachment.downloadPath ? `${base}${attachment.downloadPath}` : null;
+  if (mode === "compact" && apiUrl) {
+    return `    - ${attachment.fileName} | api: ${apiUrl} | path: ${attachment.absolutePath} | relative: ${attachment.relativePath}`;
+  }
+  const apiSuffix = apiUrl ? ` | api: ${apiUrl}` : "";
+  return `    - ${attachment.fileName} | path: ${attachment.absolutePath} | relative: ${attachment.relativePath}${apiSuffix}`;
+}
+
 export function createPrompt(context: HeartbeatContext) {
+  const isCommentOrderRunEarly = context.wakeContext?.reason === "issue_comment_recipient";
+  if (context.idleMicroPrompt && context.workItems.length === 0 && !isCommentOrderRunEarly) {
+    return buildIdleMicroPrompt(context);
+  }
   const bootstrapPrompt = context.runtime?.bootstrapPrompt?.trim();
+  const promptMode = resolveHeartbeatPromptModeForPrompt(context);
+  const isCompact = promptMode === "compact";
+  const memoryCap = resolveMemorySectionMaxChars(promptMode);
   const companyGoals = context.goalContext?.companyGoals.length
     ? context.goalContext.companyGoals.map((goal) => `- ${goal}`).join("\n")
     : "- No active company goals";
@@ -2628,6 +2687,8 @@ export function createPrompt(context: HeartbeatContext) {
     ? context.goalContext.agentGoals.map((goal) => `- ${goal}`).join("\n")
     : "- No active agent goals";
   const isCommentOrderRun = context.wakeContext?.reason === "issue_comment_recipient";
+  const controlPlaneApiBaseUrl =
+    context.runtime?.env?.BOPODEV_API_BASE_URL?.trim() || context.runtime?.env?.BOPODEV_API_URL?.trim() || "";
   const workItems = context.workItems.length
     ? context.workItems
         .map((item) =>
@@ -2638,14 +2699,18 @@ export function createPrompt(context: HeartbeatContext) {
             item.childIssueIds?.length ? `  Sub-issues: ${item.childIssueIds.join(", ")}` : null,
             item.status ? `  Status: ${item.status}` : null,
             item.priority ? `  Priority: ${item.priority}` : null,
-            item.body ? `  Body: ${item.body}` : null,
+            isCompact
+              ? `  Body: (omitted — fetch with GET ${controlPlaneApiBaseUrl || "$BOPODEV_API_BASE_URL"}/issues/${item.issueId})`
+              : item.body
+                ? `  Body: ${item.body}`
+                : null,
             item.labels?.length ? `  Labels: ${item.labels.join(", ")}` : null,
             item.tags?.length ? `  Tags: ${item.tags.join(", ")}` : null,
             item.attachments?.length
               ? [
                   "  Attachments:",
                   ...item.attachments.map((attachment) =>
-                    `    - ${attachment.fileName} | path: ${attachment.absolutePath} | relative: ${attachment.relativePath}`
+                    formatAttachmentLine(attachment, promptMode, controlPlaneApiBaseUrl || "http://127.0.0.1:4020")
                   )
                 ].join("\n")
               : null
@@ -2675,22 +2740,36 @@ export function createPrompt(context: HeartbeatContext) {
         ].join("\n")
       : "";
   const memoryContext = context.memoryContext;
-  const memoryTacitNotes = memoryContext?.tacitNotes?.trim()
+  const memoryTacitNotesRaw = memoryContext?.tacitNotes?.trim()
     ? memoryContext.tacitNotes.trim()
     : "No tacit notes were recorded yet.";
-  const memoryDurableFacts =
+  const memoryTacitNotes = clipPromptText(memoryTacitNotesRaw, memoryCap);
+  const memoryDurableFactsRaw =
     memoryContext?.durableFacts && memoryContext.durableFacts.length > 0
       ? memoryContext.durableFacts.map((fact) => `- ${fact}`).join("\n")
       : "- No durable facts available.";
-  const memoryDailyNotes =
+  const memoryDurableFacts = clipPromptText(memoryDurableFactsRaw, memoryCap);
+  const memoryDailyNotesRaw =
     memoryContext?.dailyNotes && memoryContext.dailyNotes.length > 0
       ? memoryContext.dailyNotes.map((note) => `- ${note}`).join("\n")
       : "- No recent daily notes.";
-  const controlPlaneApiBaseUrl =
-    context.runtime?.env?.BOPODEV_API_BASE_URL?.trim() || context.runtime?.env?.BOPODEV_API_URL?.trim() || "";
+  const memoryDailyNotes = clipPromptText(memoryDailyNotesRaw, memoryCap);
   const hasControlPlaneHeaders = Boolean(context.runtime?.env?.BOPODEV_REQUEST_HEADERS_JSON?.trim());
   const safeControlPlaneCurl =
     'curl -sS -H "x-company-id: $BOPODEV_COMPANY_ID" -H "x-actor-type: $BOPODEV_ACTOR_TYPE" -H "x-actor-id: $BOPODEV_ACTOR_ID" -H "x-actor-companies: $BOPODEV_ACTOR_COMPANIES" -H "x-actor-permissions: $BOPODEV_ACTOR_PERMISSIONS" "$BOPODEV_API_BASE_URL/agents"';
+  const compactHydration =
+    isCompact &&
+    (context.workItems.length > 0 ||
+      (context.wakeContext?.issueIds && context.wakeContext.issueIds.length > 0))
+      ? [
+          "Context hydration (compact prompt mode):",
+          "- Load full issue description and attachment list (with `downloadPath` for each file) via GET `$BOPODEV_API_BASE_URL`/issues/{issueId} before substantive work.",
+          "- Use the same actor headers as in the control-plane section below.",
+          `- Example: curl -sS -H "x-company-id: $BOPODEV_COMPANY_ID" -H "x-actor-type: $BOPODEV_ACTOR_TYPE" -H "x-actor-id: $BOPODEV_ACTOR_ID" -H "x-actor-companies: $BOPODEV_ACTOR_COMPANIES" -H "x-actor-permissions: $BOPODEV_ACTOR_PERMISSIONS" "${controlPlaneApiBaseUrl || "$BOPODEV_API_BASE_URL"}/issues/<issueId>"`,
+          ""
+        ].join("\n")
+      : "";
+
   const controlPlaneDirectives = [
     "Control-plane API directives:",
     controlPlaneApiBaseUrl
@@ -2742,7 +2821,7 @@ export function createPrompt(context: HeartbeatContext) {
 
   return `${bootstrapPrompt ? `${bootstrapPrompt}\n\n` : ""}You are ${context.agent.name} (${context.agent.role}), agent ${context.agentId}.
 Heartbeat run ${context.heartbeatRunId}.
-
+${isCompact ? "Prompt profile: compact (issue bodies are not inlined—use GET /issues/:id to hydrate).\n" : ""}
 Company:
 - Name: ${context.company.name}
 - Mission: ${context.company.mission ?? "No mission set"}
@@ -2755,7 +2834,7 @@ ${projectGoals}
 Agent goals:
 ${agentGoals}
 
-${isCommentOrderRun ? "Linked issue context (read-only):" : "Assigned issues:"}
+${compactHydration}${isCommentOrderRun ? "Linked issue context (read-only):" : "Assigned issues:"}
 ${workItems}
 
 ${wakeContextLines}
@@ -2775,8 +2854,7 @@ ${executionDirectives}
 
 ${controlPlaneDirectives}
 
-At the end of your response, output exactly one JSON object on a single line and nothing else. Use this exact schema:
-{"employee_comment":"markdown update to the manager","results":["short concrete outcome"],"errors":[],"artifacts":[{"kind":"file","path":"relative/path"}]}
+${HEARTBEAT_JSON_SCHEMA_FOOTER}
 `;
 }
 

package/src/runtime.ts

@@ -155,6 +155,16 @@ function providerDefaultArgs(provider: "claude_code" | "codex", config?: AgentRu
   return ["exec", "--full-auto", "--skip-git-repo-check"];
 }
 
+function shouldPassCodexReasoningEffortFlag(config?: AgentRuntimeConfig): boolean {
+  const raw = (
+    config?.env?.BOPO_CODEX_PASS_REASONING_EFFORT ?? process.env.BOPO_CODEX_PASS_REASONING_EFFORT ??
+    ""
+  )
+    .trim()
+    .toLowerCase();
+  return raw === "1" || raw === "true" || raw === "yes";
+}
+
 function providerConfigArgs(provider: "claude_code" | "codex", config?: AgentRuntimeConfig) {
   const args: string[] = [];
   if (provider === "codex") {
@@ -165,7 +175,12 @@ function providerConfigArgs(provider: "claude_code" | "codex", config?: AgentRun
       // Codex JSON events carry usage metrics we need for reliable cost accounting.
       args.push("--json");
     }
-    if (config?.thinkingEffort && config.thinkingEffort !== "auto") {
+    // Many `codex` builds reject `--reasoning-effort`; only pass when explicitly enabled.
+    if (
+      shouldPassCodexReasoningEffortFlag(config) &&
+      config?.thinkingEffort &&
+      config.thinkingEffort !== "auto"
+    ) {
       args.push("--reasoning-effort", config.thinkingEffort);
     }
     if (config?.runPolicy?.allowWebSearch) {

package/src/types.ts

@@ -21,6 +21,8 @@ export interface AgentWorkItem {
     fileSizeBytes: number;
     relativePath: string;
     absolutePath: string;
+    /** API-relative path, e.g. `/issues/{issueId}/attachments/{id}/download` */
+    downloadPath?: string;
   }>;
 }
 
@@ -41,11 +43,20 @@ export interface AgentMemoryContext {
   dailyNotes: string[];
 }
 
+export type HeartbeatPromptMode = "full" | "compact";
+
 export interface HeartbeatContext {
   companyId: string;
   agentId: string;
   providerType: AgentProviderType;
   heartbeatRunId: string;
+  /** Controls how much issue/memory text is inlined in the heartbeat prompt. Default when omitted: full. */
+  promptMode?: HeartbeatPromptMode;
+  /**
+   * When true, emit a minimal idle prompt (no assigned work). Set by the API when
+   * `BOPO_HEARTBEAT_IDLE_POLICY=micro_prompt` and there are no work items.
+   */
+  idleMicroPrompt?: boolean;
   company: {
     name: string;
     mission?: string | null;