bopodev-agent-sdk 0.1.8 → 0.1.9

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
 
-> bopodev-agent-sdk@0.1.8 build /Users/danielkrusenstrahle/Documents/Projects/Monorepo/BopoHQ/packages/agent-sdk
+> bopodev-agent-sdk@0.1.9 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.7 typecheck /Users/danielkrusenstrahle/Documents/Projects/Monorepo/BopoHQ/packages/agent-sdk
+> bopodev-agent-sdk@0.1.8 typecheck /Users/danielkrusenstrahle/Documents/Projects/Monorepo/bopohq/packages/agent-sdk
 > tsc -p tsconfig.json --noEmit
 

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

@@ -14,8 +14,6 @@ export interface RuntimeExecutionOutput {
         tokenOutput?: number;
         usdCost?: number;
         summary?: string;
-        executionMode?: "local_work" | "control_plane";
-        gatedControlPlaneReasons?: string[];
     };
 }
 export interface RuntimeAttemptTrace {

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

@@ -57,9 +57,17 @@ export interface AgentRuntimeConfig {
     args?: string[];
     cwd?: string;
     timeoutMs?: number;
+    interruptGraceSec?: number;
     retryCount?: number;
     retryBackoffMs?: number;
     env?: Record<string, string>;
+    model?: string;
+    thinkingEffort?: "auto" | "low" | "medium" | "high";
+    bootstrapPrompt?: string;
+    runPolicy?: {
+        sandboxMode?: "workspace_write" | "full_access";
+        allowWebSearch?: boolean;
+    };
 }
 export interface AdapterTrace {
     command?: string;
@@ -67,6 +75,7 @@ export interface AdapterTrace {
     elapsedMs?: number;
     timedOut?: boolean;
     failureType?: string;
+    usageSource?: "structured" | "estimated" | "none" | "unknown";
     attemptCount?: number;
     attempts?: Array<{
         attempt: number;
@@ -79,6 +88,4 @@ export interface AdapterTrace {
     }>;
     stdoutPreview?: string;
     stderrPreview?: string;
-    executionMode?: "local_work" | "control_plane";
-    gatedControlPlaneReasons?: string[];
 }

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

@@ -109,6 +109,133 @@ export declare const ProviderTypeSchema: z.ZodEnum<{
     shell: "shell";
 }>;
 export type ProviderType = z.infer<typeof ProviderTypeSchema>;
+export declare const ThinkingEffortSchema: z.ZodEnum<{
+    low: "low";
+    medium: "medium";
+    high: "high";
+    auto: "auto";
+}>;
+export type ThinkingEffort = z.infer<typeof ThinkingEffortSchema>;
+export declare const SandboxModeSchema: z.ZodEnum<{
+    workspace_write: "workspace_write";
+    full_access: "full_access";
+}>;
+export type SandboxMode = z.infer<typeof SandboxModeSchema>;
+export declare const RunPolicySchema: z.ZodObject<{
+    sandboxMode: z.ZodDefault<z.ZodEnum<{
+        workspace_write: "workspace_write";
+        full_access: "full_access";
+    }>>;
+    allowWebSearch: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+export type RunPolicy = z.infer<typeof RunPolicySchema>;
+export declare const AgentRuntimeConfigSchema: z.ZodObject<{
+    runtimeCommand: z.ZodOptional<z.ZodString>;
+    runtimeArgs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    runtimeCwd: z.ZodOptional<z.ZodString>;
+    runtimeEnv: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    runtimeModel: z.ZodOptional<z.ZodString>;
+    runtimeThinkingEffort: z.ZodDefault<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+        auto: "auto";
+    }>>;
+    bootstrapPrompt: z.ZodOptional<z.ZodString>;
+    runtimeTimeoutSec: z.ZodDefault<z.ZodNumber>;
+    interruptGraceSec: z.ZodDefault<z.ZodNumber>;
+    runPolicy: z.ZodDefault<z.ZodObject<{
+        sandboxMode: z.ZodDefault<z.ZodEnum<{
+            workspace_write: "workspace_write";
+            full_access: "full_access";
+        }>>;
+        allowWebSearch: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AgentRuntimeConfig = z.infer<typeof AgentRuntimeConfigSchema>;
+export declare const AgentCreateRequestSchema: z.ZodObject<{
+    managerAgentId: z.ZodOptional<z.ZodString>;
+    role: z.ZodString;
+    name: z.ZodString;
+    providerType: z.ZodEnum<{
+        claude_code: "claude_code";
+        codex: "codex";
+        http: "http";
+        shell: "shell";
+    }>;
+    heartbeatCron: z.ZodString;
+    monthlyBudgetUsd: z.ZodNumber;
+    canHireAgents: z.ZodDefault<z.ZodBoolean>;
+    requestApproval: z.ZodDefault<z.ZodBoolean>;
+    runtimeConfig: z.ZodDefault<z.ZodObject<{
+        runtimeCommand: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        runtimeArgs: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+        runtimeCwd: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        runtimeEnv: z.ZodOptional<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>>;
+        runtimeModel: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        runtimeThinkingEffort: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+            auto: "auto";
+        }>>>;
+        bootstrapPrompt: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        runtimeTimeoutSec: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+        interruptGraceSec: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+        runPolicy: z.ZodOptional<z.ZodDefault<z.ZodObject<{
+            sandboxMode: z.ZodDefault<z.ZodEnum<{
+                workspace_write: "workspace_write";
+                full_access: "full_access";
+            }>>;
+            allowWebSearch: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AgentCreateRequest = z.infer<typeof AgentCreateRequestSchema>;
+export declare const AgentUpdateRequestSchema: z.ZodObject<{
+    managerAgentId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    role: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    providerType: z.ZodOptional<z.ZodEnum<{
+        claude_code: "claude_code";
+        codex: "codex";
+        http: "http";
+        shell: "shell";
+    }>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        paused: "paused";
+        idle: "idle";
+        running: "running";
+        terminated: "terminated";
+    }>>;
+    heartbeatCron: z.ZodOptional<z.ZodString>;
+    monthlyBudgetUsd: z.ZodOptional<z.ZodNumber>;
+    canHireAgents: z.ZodOptional<z.ZodBoolean>;
+    runtimeConfig: z.ZodOptional<z.ZodObject<{
+        runtimeCommand: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        runtimeArgs: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
+        runtimeCwd: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        runtimeEnv: z.ZodOptional<z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>>;
+        runtimeModel: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        runtimeThinkingEffort: z.ZodOptional<z.ZodDefault<z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+            auto: "auto";
+        }>>>;
+        bootstrapPrompt: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        runtimeTimeoutSec: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+        interruptGraceSec: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+        runPolicy: z.ZodOptional<z.ZodDefault<z.ZodObject<{
+            sandboxMode: z.ZodDefault<z.ZodEnum<{
+                workspace_write: "workspace_write";
+                full_access: "full_access";
+            }>>;
+            allowWebSearch: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AgentUpdateRequest = z.infer<typeof AgentUpdateRequestSchema>;
 export declare const AgentSchema: z.ZodObject<{
     id: z.ZodString;
     companyId: z.ZodString;
@@ -132,6 +259,22 @@ export declare const AgentSchema: z.ZodObject<{
     usedBudgetUsd: z.ZodDefault<z.ZodNumber>;
     tokenUsage: z.ZodDefault<z.ZodNumber>;
     canHireAgents: z.ZodDefault<z.ZodBoolean>;
+    avatarSeed: z.ZodOptional<z.ZodString>;
+    runtimeCommand: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    runtimeArgsJson: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    runtimeCwd: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    runtimeEnvJson: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    runtimeModel: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    runtimeThinkingEffort: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        low: "low";
+        medium: "medium";
+        high: "high";
+        auto: "auto";
+    }>>>;
+    bootstrapPrompt: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    runtimeTimeoutSec: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    interruptGraceSec: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    runPolicyJson: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     createdAt: z.ZodString;
     updatedAt: z.ZodString;
 }, z.core.$strip>;
@@ -340,6 +483,7 @@ export declare const OfficeOccupantSchema: z.ZodObject<{
         http: "http";
         shell: "shell";
     }>>;
+    avatarSeed: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     focusEntityType: z.ZodNullable<z.ZodEnum<{
         agent: "agent";
         approval: "approval";
@@ -381,6 +525,7 @@ export declare const OfficeSpaceEventSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
             http: "http";
             shell: "shell";
         }>>;
+        avatarSeed: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         focusEntityType: z.ZodNullable<z.ZodEnum<{
             agent: "agent";
             approval: "approval";
@@ -421,6 +566,7 @@ export declare const OfficeSpaceEventSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
             http: "http";
             shell: "shell";
         }>>;
+        avatarSeed: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         focusEntityType: z.ZodNullable<z.ZodEnum<{
             agent: "agent";
             approval: "approval";
@@ -545,6 +691,7 @@ export declare const RealtimeEventEnvelopeSchema: z.ZodDiscriminatedUnion<[z.Zod
                 http: "http";
                 shell: "shell";
             }>>;
+            avatarSeed: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             focusEntityType: z.ZodNullable<z.ZodEnum<{
                 agent: "agent";
                 approval: "approval";
@@ -585,6 +732,7 @@ export declare const RealtimeEventEnvelopeSchema: z.ZodDiscriminatedUnion<[z.Zod
                 http: "http";
                 shell: "shell";
             }>>;
+            avatarSeed: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             focusEntityType: z.ZodNullable<z.ZodEnum<{
                 agent: "agent";
                 approval: "approval";
@@ -717,6 +865,7 @@ export declare const RealtimeEventMessageSchema: z.ZodDiscriminatedUnion<[z.ZodO
                 http: "http";
                 shell: "shell";
             }>>;
+            avatarSeed: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             focusEntityType: z.ZodNullable<z.ZodEnum<{
                 agent: "agent";
                 approval: "approval";
@@ -757,6 +906,7 @@ export declare const RealtimeEventMessageSchema: z.ZodDiscriminatedUnion<[z.ZodO
                 http: "http";
                 shell: "shell";
             }>>;
+            avatarSeed: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             focusEntityType: z.ZodNullable<z.ZodEnum<{
                 agent: "agent";
                 approval: "approval";
@@ -887,6 +1037,7 @@ export declare const RealtimeMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
                 http: "http";
                 shell: "shell";
             }>>;
+            avatarSeed: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             focusEntityType: z.ZodNullable<z.ZodEnum<{
                 agent: "agent";
                 approval: "approval";
@@ -927,6 +1078,7 @@ export declare const RealtimeMessageSchema: z.ZodUnion<readonly [z.ZodObject<{
                 http: "http";
                 shell: "shell";
             }>>;
+            avatarSeed: z.ZodOptional<z.ZodNullable<z.ZodString>>;
             focusEntityType: z.ZodNullable<z.ZodEnum<{
                 agent: "agent";
                 approval: "approval";

package/package.json

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

package/src/adapters.ts

@@ -54,19 +54,12 @@ export class GenericHeartbeatAdapter implements AgentAdapter {
       };
     }
 
-    const credentialState = resolveControlPlaneCredentialState(context);
-    const prompt = createPrompt(context, credentialState);
+    const prompt = createPrompt(context);
     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
-        ),
+        summary: runtime.parsedUsage?.summary ?? `${this.providerType} runtime finished in ${runtime.elapsedMs}ms.`,
         tokenInput: runtime.parsedUsage?.tokenInput ?? 0,
         tokenOutput: runtime.parsedUsage?.tokenOutput ?? 0,
         usdCost: runtime.parsedUsage?.usdCost ?? 0,
@@ -79,24 +72,22 @@ export class GenericHeartbeatAdapter implements AgentAdapter {
           attemptCount: runtime.attemptCount,
           attempts: runtime.attempts,
           stdoutPreview: toPreview(runtime.stdout),
-          stderrPreview: toPreview(runtime.stderr),
-          executionMode,
-          gatedControlPlaneReasons
+          stderrPreview: toPreview(runtime.stderr)
         },
         nextState: withProviderMetadata(context, this.providerType, runtime.elapsedMs, runtime.code)
       };
     }
 
+    const failedUsage = resolveFailedUsage(runtime, prompt, {
+      inputRate: 0.000001,
+      outputRate: 0.000004
+    });
     return {
       status: "failed",
-      summary: withExecutionDiagnostics(
-        `${this.providerType} runtime failed: ${runtime.stderr || "unknown error"}`,
-        executionMode,
-        gatedControlPlaneReasons
-      ),
-      tokenInput: 0,
-      tokenOutput: 0,
-      usdCost: 0,
+      summary: runtime.parsedUsage?.summary ?? `${this.providerType} runtime failed: ${runtime.stderr || "unknown error"}`,
+      tokenInput: failedUsage.tokenInput,
+      tokenOutput: failedUsage.tokenOutput,
+      usdCost: failedUsage.usdCost,
       trace: {
         command: context.runtime.command,
         exitCode: runtime.code,
@@ -105,10 +96,9 @@ export class GenericHeartbeatAdapter implements AgentAdapter {
         failureType: runtime.failureType,
         attemptCount: runtime.attemptCount,
         attempts: runtime.attempts,
+        usageSource: failedUsage.source,
         stdoutPreview: toPreview(runtime.stdout),
-        stderrPreview: toPreview(runtime.stderr),
-        executionMode,
-        gatedControlPlaneReasons
+        stderrPreview: toPreview(runtime.stderr)
       },
       nextState: context.state
     };
@@ -131,11 +121,8 @@ async function runProviderWork(
   provider: "claude_code" | "codex",
   pricing: { inputRate: number; outputRate: number }
 ): Promise<AdapterExecutionResult> {
-  const credentialState = resolveControlPlaneCredentialState(context);
-  const prompt = createPrompt(context, credentialState);
+  const prompt = createPrompt(context);
   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);
@@ -144,11 +131,7 @@ async function runProviderWork(
     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
-    );
+    const summary = runtime.parsedUsage?.summary ?? `${provider} runtime finished in ${runtime.elapsedMs}ms.`;
 
     return {
       status: "ok",
@@ -165,23 +148,18 @@ async function runProviderWork(
         attemptCount: runtime.attemptCount,
         attempts: runtime.attempts,
         stdoutPreview: toPreview(runtime.stdout),
-        stderrPreview: toPreview(runtime.stderr),
-        executionMode,
-        gatedControlPlaneReasons
+        stderrPreview: toPreview(runtime.stderr)
       },
       nextState: withProviderMetadata(context, provider, runtime.elapsedMs, runtime.code)
     };
   }
+  const failedUsage = resolveFailedUsage(runtime, prompt, pricing);
   return {
     status: "failed",
-    summary: withExecutionDiagnostics(
-      `${provider} runtime failed: ${runtime.stderr || "unknown error"}`,
-      executionMode,
-      gatedControlPlaneReasons
-    ),
-    tokenInput: 0,
-    tokenOutput: 0,
-    usdCost: 0,
+    summary: runtime.parsedUsage?.summary ?? `${provider} runtime failed: ${runtime.stderr || "unknown error"}`,
+    tokenInput: failedUsage.tokenInput,
+    tokenOutput: failedUsage.tokenOutput,
+    usdCost: failedUsage.usdCost,
     trace: {
       command: context.runtime?.command ?? provider,
       exitCode: runtime.code,
@@ -190,16 +168,58 @@ async function runProviderWork(
       failureType: runtime.failureType,
       attemptCount: runtime.attemptCount,
       attempts: runtime.attempts,
+      usageSource: failedUsage.source,
       stdoutPreview: toPreview(runtime.stdout),
-      stderrPreview: toPreview(runtime.stderr),
-      executionMode,
-      gatedControlPlaneReasons
+      stderrPreview: toPreview(runtime.stderr)
     },
     nextState: context.state
   };
 }
 
-function createPrompt(context: HeartbeatContext, credentialState = resolveControlPlaneCredentialState(context)) {
+function resolveFailedUsage(
+  runtime: {
+    parsedUsage?: {
+      tokenInput?: number;
+      tokenOutput?: number;
+      usdCost?: number;
+      summary?: string;
+    };
+    failureType?: "timeout" | "spawn_error" | "nonzero_exit";
+    stdout: string;
+    stderr: string;
+  },
+  prompt: string,
+  pricing: { inputRate: number; outputRate: number }
+) {
+  if (runtime.parsedUsage) {
+    return {
+      tokenInput: runtime.parsedUsage.tokenInput ?? 0,
+      tokenOutput: runtime.parsedUsage.tokenOutput ?? 0,
+      usdCost: runtime.parsedUsage.usdCost ?? 0,
+      source: "structured" as const
+    };
+  }
+  if (runtime.failureType === "spawn_error") {
+    return {
+      tokenInput: 0,
+      tokenOutput: 0,
+      usdCost: 0,
+      source: "none" as const
+    };
+  }
+  const estimatedInput = Math.max(1, Math.floor(prompt.length / 4));
+  const estimatedOutput = Math.max(1, Math.floor((runtime.stdout.length + runtime.stderr.length) / 8));
+  const estimatedCost = Number((estimatedInput * pricing.inputRate + estimatedOutput * pricing.outputRate).toFixed(6));
+  return {
+    tokenInput: estimatedInput,
+    tokenOutput: estimatedOutput,
+    usdCost: estimatedCost,
+    source: "estimated" as const
+  };
+}
+
+function createPrompt(context: HeartbeatContext) {
+  const bootstrapPrompt = context.runtime?.bootstrapPrompt?.trim();
   const companyGoals = context.goalContext?.companyGoals.length
     ? context.goalContext.companyGoals.map((goal) => `- ${goal}`).join("\n")
     : "- No active company goals";
@@ -230,20 +250,19 @@ function createPrompt(context: HeartbeatContext, credentialState = resolveContro
   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.",
+    "- Use BopoHQ-specific injected skills only (bopohq-control-plane, bopohq-create-agent, para-memory-files) when relevant.",
+    "- Ignore unrelated third-party control-plane skills even if they exist in the runtime environment.",
+    "- Prefer completing assigned issue work in this repository over non-essential coordination tasks.",
     "- 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}`)
+    "- Shell commands run under zsh on macOS; avoid Bash-only features such as `local -n`, `declare -n`, `mapfile`, and `readarray`.",
+    "- Prefer POSIX/zsh-compatible shell snippets, direct `curl` headers, `jq`, and temp JSON files/heredocs.",
+    "- If control-plane API connectivity fails, report the exact failing command/error once and stop retry loops for the same endpoint.",
+    "- If any command fails, avoid further exploratory commands and still return the required final JSON summary.",
+    "- Your final output must be only the JSON object below, with no prose before or after it.",
+    "- Do not invent token or cost values; the runtime records usage separately."
   ].join("\n");
 
-  return `You are ${context.agent.name} (${context.agent.role}), agent ${context.agentId}.
+  return `${bootstrapPrompt ? `${bootstrapPrompt}\n\n` : ""}You are ${context.agent.name} (${context.agent.role}), agent ${context.agentId}.
 Heartbeat run ${context.heartbeatRunId}.
 
 Company:
@@ -262,42 +281,12 @@ 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":["..."]}
+At the end of your response, output exactly one JSON object on a single line and nothing else:
+{"summary":"brief outcome and any blocker"}
 `;
 }
 
-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,

package/src/runtime.ts

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { access, lstat, mkdir, mkdtemp, readdir, rm, symlink } from "node:fs/promises";
+import { access, cp, 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";
@@ -20,8 +20,6 @@ export interface RuntimeExecutionOutput {
     tokenOutput?: number;
     usdCost?: number;
     summary?: string;
-    executionMode?: "local_work" | "control_plane";
-    gatedControlPlaneReasons?: string[];
   };
 }
 
@@ -50,13 +48,73 @@ function pickDefaultCommand(provider: "claude_code" | "codex") {
   return "codex";
 }
 
-function providerDefaultArgs(provider: "claude_code" | "codex") {
+function providerDefaultArgs(provider: "claude_code" | "codex", config?: AgentRuntimeConfig) {
   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"];
+  // Codex CLI rejects combining --full-auto with sandbox bypass flags.
+  if (shouldBypassCodexSandbox(config)) {
+    return ["exec", "--skip-git-repo-check"];
+  }
+  // Include skip-git-repo-check to allow execution from deterministic fallback workspaces
+  // that may not be trusted git directories.
+  return ["exec", "--full-auto", "--skip-git-repo-check"];
+}
+
+function providerConfigArgs(provider: "claude_code" | "codex", config?: AgentRuntimeConfig) {
+  const args: string[] = [];
+  if (provider === "codex") {
+    if (config?.model?.trim()) {
+      args.push("--model", config.model.trim());
+    }
+    if (config?.thinkingEffort && config.thinkingEffort !== "auto") {
+      args.push("--reasoning-effort", config.thinkingEffort);
+    }
+    if (config?.runPolicy?.allowWebSearch) {
+      args.push("--search");
+    }
+    if (shouldBypassCodexSandbox(config)) {
+      args.push("--dangerously-bypass-approvals-and-sandbox");
+    }
+  }
+  if (provider === "claude_code") {
+    if (config?.model?.trim()) {
+      args.push("--model", config.model.trim());
+    }
+    if (config?.thinkingEffort && config.thinkingEffort !== "auto") {
+      args.push("--effort", config.thinkingEffort);
+    }
+    if (config?.runPolicy?.sandboxMode === "full_access") {
+      args.push("--dangerously-skip-permissions");
+    }
+  }
+  return args;
+}
+
+function shouldBypassCodexSandbox(config?: AgentRuntimeConfig) {
+  if (config?.runPolicy?.sandboxMode === "full_access") {
+    return true;
+  }
+  const env = config?.env;
+  if (!env) {
+    return false;
+  }
+  const hasControlPlaneContext =
+    typeof env.BOPOHQ_API_BASE_URL === "string" &&
+    env.BOPOHQ_API_BASE_URL.trim().length > 0 &&
+    typeof env.BOPOHQ_REQUEST_HEADERS_JSON === "string" &&
+    env.BOPOHQ_REQUEST_HEADERS_JSON.trim().length > 0;
+  if (!hasControlPlaneContext) {
+    return false;
+  }
+  const enforceSandbox = String(env.BOPOHQ_ENFORCE_SANDBOX ?? "")
+    .trim()
+    .toLowerCase();
+  if (enforceSandbox === "1" || enforceSandbox === "true") {
+    return false;
+  }
+  return true;
 }
 
 export async function executeAgentRuntime(
@@ -67,7 +125,8 @@ export async function executeAgentRuntime(
   const commandOverride = Boolean(config?.command && config.command.trim().length > 0);
   const effectiveRetryCount = config?.retryCount ?? (provider === "codex" ? 1 : 0);
   const mergedArgs = [
-    ...(commandOverride ? [] : providerDefaultArgs(provider)),
+    ...(commandOverride ? [] : providerDefaultArgs(provider, config)),
+    ...(commandOverride ? [] : providerConfigArgs(provider, config)),
     ...(config?.args ?? [])
   ];
   return executePromptRuntime(
@@ -88,12 +147,16 @@ export async function executePromptRuntime(
 ): Promise<RuntimeExecutionOutput> {
   const baseArgs = [...(config?.args ?? [])];
   const timeoutMs = config?.timeoutMs ?? 120_000;
+  const interruptGraceMs = Math.max(0, config?.interruptGraceSec ?? 2) * 1000;
   const maxAttempts = Math.max(1, Math.min(3, 1 + (config?.retryCount ?? 0)));
   const retryBackoffMs = Math.max(100, config?.retryBackoffMs ?? 400);
-  const env = {
+  const mergedEnv = {
     ...process.env,
     ...(config?.env ?? {})
   };
+  const normalizedEnv = normalizeProviderAuthEnv(options?.provider, mergedEnv);
+  const providerIsolation = await withProviderRuntimeIsolation(options?.provider, normalizedEnv);
+  const env = providerIsolation.env;
   const provider = options?.provider;
   const injection = await prepareSkillInjection(provider, env);
   const args = [...baseArgs, ...injection.additionalArgs, prompt];
@@ -112,9 +175,17 @@ export async function executePromptRuntime(
     | undefined;
   try {
     for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
-      const attemptResult = await executeSinglePromptAttempt(command, args, config?.cwd || process.cwd(), env, timeoutMs);
+      const attemptResult = await executeSinglePromptAttempt(
+        command,
+        args,
+        config?.cwd || process.cwd(),
+        env,
+        timeoutMs,
+        interruptGraceMs
+      );
+      const normalizedStderr = provider === "codex" ? stripCodexRolloutNoise(attemptResult.stderr) : attemptResult.stderr;
       stdout += attemptResult.stdout;
-      stderr = [stderr, attemptResult.stderr].filter(Boolean).join("\n").trim();
+      stderr = [stderr, normalizedStderr].filter(Boolean).join("\n").trim();
       attempts.push({
         attempt,
         code: attemptResult.code,
@@ -151,7 +222,11 @@ export async function executePromptRuntime(
         attemptResult.spawnErrorCode && TRANSIENT_SPAWN_ERROR_CODES.has(attemptResult.spawnErrorCode)
       );
       const retryableCodexNonZero =
-        provider === "codex" && !attemptResult.timedOut && !attemptResult.spawnErrorCode && attemptResult.code !== 0;
+        provider === "codex" &&
+        !attemptResult.timedOut &&
+        !attemptResult.spawnErrorCode &&
+        attemptResult.code !== 0 &&
+        !containsCodexAuthFailure(`${attemptResult.stdout}\n${normalizedStderr}`);
       const retryable = retryableSpawnError || retryableCodexNonZero;
       if (!retryable || attempt >= maxAttempts) {
         break;
@@ -172,6 +247,7 @@ export async function executePromptRuntime(
       parsedUsage: parseStructuredUsage(stdout)
     };
   } finally {
+    await providerIsolation.cleanup();
     await injection.cleanup();
   }
 }
@@ -179,6 +255,11 @@ export async function executePromptRuntime(
 const SKILLS_DIR_NAME = "skills";
 const CLAUDE_SKILLS_DIR = ".claude/skills";
 const SKILL_MD = "SKILL.md";
+const DEFAULT_CODEX_HOME_ROOT = ".bopodev/runtime/codex-home";
+const DEFAULT_CODEX_HOME_FALLBACK = ".codex";
+const CODEX_VOLATILE_STATE_ENTRIES = ["rollouts", "state.db", "data/rollouts", "data/state.db"];
+const CODEX_ROLLOUT_NOISE_RE =
+  /^\d{4}-\d{2}-\d{2}T[^\s]+\s+ERROR\s+codex_core::rollout::list:\s+state db missing rollout path for thread\s+[a-z0-9-]+$/i;
 
 type SkillInjectionContext = {
   additionalArgs: string[];
@@ -238,14 +319,13 @@ function noSkillInjection(): SkillInjectionContext {
 }
 
 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
+  timeoutMs: number,
+  interruptGraceMs: number
 ) {
   const startedAt = Date.now();
   return new Promise<{
@@ -279,7 +359,7 @@ async function executeSinglePromptAttempt(
           forcedKill = true;
           child.kill("SIGKILL");
         }
-      }, FORCE_KILL_AFTER_MS);
+      }, interruptGraceMs);
     }, timeoutMs);
 
     child.stdout.on("data", (chunk) => {
@@ -352,6 +432,14 @@ function sleep(ms: number) {
   return new Promise<void>((resolve) => setTimeout(resolve, ms));
 }
 
+function containsCodexAuthFailure(text: string) {
+  const normalized = text.toLowerCase();
+  if (!normalized.includes("401 unauthorized")) {
+    return false;
+  }
+  return normalized.includes("missing bearer") || normalized.includes("authentication");
+}
+
 export async function checkRuntimeCommandHealth(
   command: string,
   options?: { cwd?: string; timeoutMs?: number }
@@ -450,7 +538,155 @@ function resolveCodexHome(env: NodeJS.ProcessEnv) {
   if (configured) {
     return configured;
   }
-  return join(homedir(), ".codex");
+  return join(homedir(), DEFAULT_CODEX_HOME_FALLBACK);
+}
+
+function normalizeProviderAuthEnv(
+  provider: "claude_code" | "codex" | undefined,
+  env: NodeJS.ProcessEnv
+) {
+  if (provider !== "codex") {
+    return env;
+  }
+  const apiKey = env.OPENAI_API_KEY;
+  if (typeof apiKey === "string" && apiKey.trim().length === 0) {
+    const nextEnv = { ...env };
+    delete nextEnv.OPENAI_API_KEY;
+    return nextEnv;
+  }
+  return env;
+}
+
+type ProviderIsolationContext = {
+  env: NodeJS.ProcessEnv;
+  cleanup: () => Promise<void>;
+};
+
+async function withProviderRuntimeIsolation(
+  provider: "claude_code" | "codex" | undefined,
+  env: NodeJS.ProcessEnv
+): Promise<ProviderIsolationContext> {
+  if (provider !== "codex") {
+    return {
+      env,
+      cleanup: async () => {}
+    };
+  }
+  const forceManagedCodexHome = env.BOPOHQ_FORCE_MANAGED_CODEX_HOME === "true";
+  if (env.CODEX_HOME?.trim() && !forceManagedCodexHome) {
+    await sanitizeCodexHomeVolatileState(env.CODEX_HOME.trim());
+    return {
+      env,
+      cleanup: async () => {}
+    };
+  }
+  const hasApiKey = typeof env.OPENAI_API_KEY === "string" && env.OPENAI_API_KEY.trim().length > 0;
+  if (hasApiKey) {
+    const runScopedCodexHome = await mkdtemp(join(tmpdir(), "bopohq-codex-home-run-"));
+    await sanitizeCodexHomeVolatileState(runScopedCodexHome);
+    return {
+      env: {
+        ...env,
+        CODEX_HOME: runScopedCodexHome
+      },
+      cleanup: async () => {
+        await rm(runScopedCodexHome, { recursive: true, force: true });
+      }
+    };
+  }
+  if (!forceManagedCodexHome) {
+    return {
+      env: {
+        ...env,
+        CODEX_HOME: resolveCodexHome(env)
+      },
+      cleanup: async () => {}
+    };
+  }
+  const targetCodexHome = resolveManagedCodexHome(env);
+  await prepareManagedCodexHome(targetCodexHome, env);
+  return {
+    env: {
+      ...env,
+      CODEX_HOME: targetCodexHome
+    },
+    cleanup: async () => {}
+  };
+}
+
+function resolveManagedCodexHome(env: NodeJS.ProcessEnv) {
+  const managedRoot = resolveManagedCodexHomeRoot(env);
+  const companyId = sanitizePathSegment(env.BOPOHQ_COMPANY_ID);
+  const agentId = sanitizePathSegment(env.BOPOHQ_AGENT_ID);
+  if (companyId && agentId) {
+    return join(managedRoot, companyId, agentId);
+  }
+  return join(managedRoot, "shared");
+}
+
+function resolveManagedCodexHomeRoot(env: NodeJS.ProcessEnv) {
+  const configuredRoot = env.BOPO_CODEX_HOME_ROOT?.trim();
+  if (configuredRoot) {
+    return configuredRoot;
+  }
+  return join(tmpdir(), "bopohq-codex-home");
+}
+
+async function prepareManagedCodexHome(targetCodexHome: string, env: NodeJS.ProcessEnv) {
+  await mkdir(targetCodexHome, { recursive: true });
+  await seedCodexHomeIfEmpty(targetCodexHome, env);
+  await sanitizeCodexHomeVolatileState(targetCodexHome);
+}
+
+async function seedCodexHomeIfEmpty(targetCodexHome: string, env: NodeJS.ProcessEnv) {
+  if (env.BOPO_CODEX_ALLOW_HOME_SEED !== "true") {
+    return;
+  }
+  const currentEntries = await readdir(targetCodexHome).catch(() => []);
+  if (currentEntries.length > 0) {
+    return;
+  }
+  const sourceCodexHome = join(homedir(), DEFAULT_CODEX_HOME_FALLBACK);
+  const sourceEntries = await readdir(sourceCodexHome, { withFileTypes: true }).catch(() => []);
+  for (const entry of sourceEntries) {
+    if (CODEX_VOLATILE_STATE_ENTRIES.includes(entry.name)) {
+      continue;
+    }
+    const source = join(sourceCodexHome, entry.name);
+    const target = join(targetCodexHome, entry.name);
+    await cp(source, target, {
+      recursive: true,
+      force: false,
+      errorOnExist: false
+    }).catch(() => undefined);
+  }
+}
+
+async function sanitizeCodexHomeVolatileState(codexHome: string) {
+  for (const entry of CODEX_VOLATILE_STATE_ENTRIES) {
+    await rm(join(codexHome, entry), { recursive: true, force: true });
+  }
+}
+
+function stripCodexRolloutNoise(text: string) {
+  return text
+    .split(/\r?\n/)
+    .filter((line) => {
+      const trimmed = line.trim();
+      return !trimmed || !CODEX_ROLLOUT_NOISE_RE.test(trimmed);
+    })
+    .join("\n");
+}
+
+function sanitizePathSegment(value: string | undefined) {
+  if (!value) {
+    return null;
+  }
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return null;
+  }
+  return trimmed.replace(/[^a-zA-Z0-9._-]/g, "_");
 }
 
 async function buildClaudeSkillsAddDir(skillsSourceDir: string) {
@@ -525,27 +761,18 @@ function tryParseUsage(candidate: string) {
     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)) {
+    if (isPromptTemplateUsage(summary, tokenInput, tokenOutput, usdCost)) {
       return undefined;
     }
     if (
       tokenInput === undefined &&
       tokenOutput === undefined &&
       usdCost === undefined &&
-      !summary &&
-      !executionMode &&
-      !gatedControlPlaneReasons
+      !summary
     ) {
       return undefined;
     }
-    return { tokenInput, tokenOutput, usdCost, summary, executionMode, gatedControlPlaneReasons };
+    return { tokenInput, tokenOutput, usdCost, summary };
   } catch {
     return undefined;
   }
@@ -555,19 +782,21 @@ function isPromptTemplateUsage(
   summary: string | undefined,
   tokenInput: number | undefined,
   tokenOutput: number | undefined,
-  usdCost: number | undefined,
-  executionMode: "local_work" | "control_plane" | undefined,
-  gatedControlPlaneReasons: string[] | undefined
+  usdCost: number | undefined
 ) {
+  if (
+    summary?.trim().toLowerCase() === "brief outcome and any blocker" &&
+    tokenInput === undefined &&
+    tokenOutput === undefined &&
+    usdCost === undefined
+  ) {
+    return true;
+  }
   return (
     summary === "..." &&
     tokenInput === 123 &&
     tokenOutput === 456 &&
-    usdCost === 0.123456 &&
-    executionMode === "local_work" &&
-    Array.isArray(gatedControlPlaneReasons) &&
-    gatedControlPlaneReasons.length === 1 &&
-    gatedControlPlaneReasons[0] === "..."
+    usdCost === 0.123456
   );
 }
 

package/src/types.ts

@@ -64,9 +64,17 @@ export interface AgentRuntimeConfig {
   args?: string[];
   cwd?: string;
   timeoutMs?: number;
+  interruptGraceSec?: number;
   retryCount?: number;
   retryBackoffMs?: number;
   env?: Record<string, string>;
+  model?: string;
+  thinkingEffort?: "auto" | "low" | "medium" | "high";
+  bootstrapPrompt?: string;
+  runPolicy?: {
+    sandboxMode?: "workspace_write" | "full_access";
+    allowWebSearch?: boolean;
+  };
 }
 
 export interface AdapterTrace {
@@ -75,6 +83,7 @@ export interface AdapterTrace {
   elapsedMs?: number;
   timedOut?: boolean;
   failureType?: string;
+  usageSource?: "structured" | "estimated" | "none" | "unknown";
   attemptCount?: number;
   attempts?: Array<{
     attempt: number;
@@ -87,6 +96,4 @@ export interface AdapterTrace {
   }>;
   stdoutPreview?: string;
   stderrPreview?: string;
-  executionMode?: "local_work" | "control_plane";
-  gatedControlPlaneReasons?: string[];
 }

package/.turbo/turbo-lint.log

@@ -1,4 +0,0 @@
-
-> @bopo/agent-sdk@0.1.0 lint /Users/danielkrusenstrahle/Documents/Projects/Monorepo/BopoHQ/packages/agent-sdk
-> tsc -p tsconfig.json --noEmit
-