bopodev-agent-sdk 0.1.25 → 0.1.27

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
 
-> bopodev-agent-sdk@0.1.25 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/adapters.d.ts

@@ -1,5 +1,13 @@
 import type { AdapterEnvironmentCheck, AdapterEnvironmentResult, AdapterExecutionResult, AdapterMetadata, AdapterModelOption, AdapterNormalizedUsage, AgentAdapter, AgentProviderType, AgentRuntimeConfig, HeartbeatContext } from "./types";
 import { type DirectApiProvider } from "./runtime-http";
+import { classifyProviderFailure as classifyProviderFailureByProvider } from "./provider-failures";
+export declare function normalizeProviderFailureDetail(provider: AgentProviderType, detail: string): string;
+export declare function classifyProviderFailure(provider: AgentProviderType, input: {
+    detail: string;
+    stderr?: string;
+    stdout?: string;
+    failureType?: string | null;
+}): ReturnType<typeof classifyProviderFailureByProvider>;
 type RuntimeParsedUsage = {
     tokenInput?: number;
     tokenOutput?: number;
@@ -114,6 +122,7 @@ export declare function toProviderResult(context: HeartbeatContext, provider: Ag
         forcedKill: boolean;
     }>;
     parsedUsage?: RuntimeParsedUsage;
+    finalRunOutput?: AdapterExecutionResult["finalRunOutput"];
     structuredOutputSource?: "stdout" | "stderr";
     structuredOutputDiagnostics?: {
         stdoutJsonObjectCount: number;
@@ -125,6 +134,8 @@ export declare function toProviderResult(context: HeartbeatContext, provider: Ag
         lastStdoutLine?: string;
         lastStderrLine?: string;
         likelyCause: "no_output_from_runtime" | "json_missing" | "json_on_stderr_only" | "schema_or_shape_mismatch";
+        finalRunOutputStatus?: "valid" | "missing" | "malformed" | "schema_mismatch";
+        finalRunOutputError?: string;
         claudeStopReason?: string;
         claudeResultSubtype?: string;
         claudeSessionId?: string;
@@ -165,7 +176,7 @@ export declare function resolveRuntimeFailureDetail(runtime: {
     attempts: Array<{
         spawnErrorCode?: string;
     }>;
-}): string;
+}, provider?: AgentProviderType): string;
 export declare function parseOpenCodeOutput(stdout: string): {
     sessionId: string | null;
 };

package/dist/agent-sdk/src/provider-failures/anthropic-api.d.ts

@@ -0,0 +1,5 @@
+import type { ProviderFailureNormalizer } from "./types";
+export declare const anthropicApiFailureResolver: {
+    normalize: ProviderFailureNormalizer;
+    classify: import("./types").ProviderFailureClassifier;
+};

package/dist/agent-sdk/src/provider-failures/claude-code.d.ts

@@ -0,0 +1,5 @@
+import type { ProviderFailureNormalizer } from "./types";
+export declare const claudeCodeFailureResolver: {
+    normalize: ProviderFailureNormalizer;
+    classify: import("./types").ProviderFailureClassifier;
+};

package/dist/agent-sdk/src/provider-failures/codex.d.ts

@@ -0,0 +1,5 @@
+import type { ProviderFailureNormalizer } from "./types";
+export declare const codexFailureResolver: {
+    normalize: ProviderFailureNormalizer;
+    classify: import("./types").ProviderFailureClassifier;
+};

package/dist/agent-sdk/src/provider-failures/common.d.ts

@@ -0,0 +1,7 @@
+import type { ProviderFailureClassification, ProviderFailureClassifier, ProviderFailureInput, ProviderFailureNormalizer } from "./types";
+export declare function normalizeWhitespace(value: string): string;
+export declare function hasModelUnsupportedSignal(haystack: string): boolean;
+export declare function hasAuthFailureSignal(haystack: string): boolean;
+export declare function hasUnknownSessionSignal(haystack: string): boolean;
+export declare function classifyFromSignals(normalize: ProviderFailureNormalizer, input: ProviderFailureInput): ProviderFailureClassification;
+export declare function createClassifier(normalize: ProviderFailureNormalizer): ProviderFailureClassifier;

package/dist/agent-sdk/src/provider-failures/cursor.d.ts

@@ -0,0 +1,5 @@
+import type { ProviderFailureNormalizer } from "./types";
+export declare const cursorFailureResolver: {
+    normalize: ProviderFailureNormalizer;
+    classify: import("./types").ProviderFailureClassifier;
+};

package/dist/agent-sdk/src/provider-failures/gemini-cli.d.ts

@@ -0,0 +1,5 @@
+import type { ProviderFailureNormalizer } from "./types";
+export declare const geminiCliFailureResolver: {
+    normalize: ProviderFailureNormalizer;
+    classify: import("./types").ProviderFailureClassifier;
+};

package/dist/agent-sdk/src/provider-failures/http.d.ts

@@ -0,0 +1,5 @@
+import type { ProviderFailureNormalizer } from "./types";
+export declare const httpFailureResolver: {
+    normalize: ProviderFailureNormalizer;
+    classify: import("./types").ProviderFailureClassifier;
+};

package/dist/agent-sdk/src/provider-failures/index.d.ts

@@ -0,0 +1,5 @@
+import type { AgentProviderType } from "../types";
+import type { ProviderFailureClassification, ProviderFailureInput } from "./types";
+export declare function normalizeProviderFailureDetail(provider: AgentProviderType, detail: string): string;
+export declare function classifyProviderFailure(provider: AgentProviderType, input: ProviderFailureInput): ProviderFailureClassification;
+export type { ProviderFailureClassification, ProviderFailureInput } from "./types";

package/dist/agent-sdk/src/provider-failures/openai-api.d.ts

@@ -0,0 +1,5 @@
+import type { ProviderFailureNormalizer } from "./types";
+export declare const openAiApiFailureResolver: {
+    normalize: ProviderFailureNormalizer;
+    classify: import("./types").ProviderFailureClassifier;
+};

package/dist/agent-sdk/src/provider-failures/opencode.d.ts

@@ -0,0 +1,5 @@
+import type { ProviderFailureNormalizer } from "./types";
+export declare const opencodeFailureResolver: {
+    normalize: ProviderFailureNormalizer;
+    classify: import("./types").ProviderFailureClassifier;
+};

package/dist/agent-sdk/src/provider-failures/shell.d.ts

@@ -0,0 +1,5 @@
+import type { ProviderFailureNormalizer } from "./types";
+export declare const shellFailureResolver: {
+    normalize: ProviderFailureNormalizer;
+    classify: import("./types").ProviderFailureClassifier;
+};

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

@@ -0,0 +1,20 @@
+import type { AgentProviderType } from "../types";
+export type ProviderFailureInput = {
+    detail: string;
+    stderr?: string;
+    stdout?: string;
+    failureType?: string | null;
+};
+export type ProviderFailureClassification = {
+    detail: string;
+    blockerCode: string;
+    retryable: boolean;
+    providerUsageLimited: boolean;
+};
+export type ProviderFailureClassifier = (input: ProviderFailureInput) => ProviderFailureClassification;
+export type ProviderFailureNormalizer = (detail: string) => string;
+export type ProviderFailureResolver = {
+    normalize: ProviderFailureNormalizer;
+    classify: ProviderFailureClassifier;
+};
+export type ProviderFailureResolverMap = Partial<Record<AgentProviderType, ProviderFailureResolver>>;

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/runtime-core.d.ts

@@ -1,2 +1,2 @@
 export type { RuntimeAttemptTrace, RuntimeCommandHealth, RuntimeExecutionOutput, RuntimeTranscriptEvent } from "./runtime";
-export { checkRuntimeCommandHealth, containsRateLimitFailure, executeAgentRuntime, executePromptRuntime } from "./runtime";
+export { checkRuntimeCommandHealth, containsUsageLimitHardStopFailure, containsRateLimitFailure, executeAgentRuntime, executePromptRuntime } from "./runtime";

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

@@ -1,4 +1,5 @@
 import type { AgentRuntimeConfig } from "./types";
+import type { AgentFinalRunOutput } from "bopodev-contracts";
 export type DirectApiProvider = "openai_api" | "anthropic_api";
 export type DirectApiExecutionOutput = {
     ok: boolean;
@@ -8,10 +9,11 @@ export type DirectApiExecutionOutput = {
     elapsedMs: number;
     statusCode: number;
     summary?: string;
+    finalRunOutput?: AgentFinalRunOutput;
     tokenInput?: number;
     tokenOutput?: number;
     usdCost?: number;
-    failureType?: "auth" | "rate_limit" | "timeout" | "network" | "bad_response" | "http_error";
+    failureType?: "auth" | "rate_limit" | "out_of_funds" | "quota_exhausted" | "timeout" | "network" | "bad_response" | "http_error";
     error?: string;
     responsePreview?: string;
     attemptCount: number;
@@ -19,7 +21,7 @@ export type DirectApiExecutionOutput = {
         attempt: number;
         statusCode: number;
         elapsedMs: number;
-        failureType?: "auth" | "rate_limit" | "timeout" | "network" | "bad_response" | "http_error";
+        failureType?: "auth" | "rate_limit" | "out_of_funds" | "quota_exhausted" | "timeout" | "network" | "bad_response" | "http_error";
         error?: string;
     }>;
 };

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

@@ -1 +1 @@
-export { parseClaudeStreamOutput, parseCursorStreamOutput, parseGeminiStreamOutput, parseRuntimeTranscript, parseStructuredUsage } from "./runtime";
+export { parseAgentFinalRunOutput, parseClaudeStreamOutput, parseCursorStreamOutput, parseGeminiStreamOutput, parseRuntimeTranscript, parseStructuredUsage } from "./runtime";

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

@@ -1,3 +1,4 @@
+import { type AgentFinalRunOutput } from "bopodev-contracts";
 import type { AgentRuntimeConfig } from "./types";
 type LocalProvider = "claude_code" | "codex" | "cursor" | "opencode" | "gemini_cli";
 type ClaudeContractDiagnostics = {
@@ -19,6 +20,7 @@ type ParsedUsageRecord = {
     usdCost?: number;
     summary?: string;
 };
+type FinalRunOutputParseError = "missing" | "malformed" | "schema_mismatch";
 type CursorParsedStream = {
     usage: ParsedUsageRecord;
     sessionId?: string;
@@ -43,6 +45,8 @@ export interface RuntimeExecutionOutput {
         usdCost?: number;
         summary?: string;
     };
+    finalRunOutput?: AgentFinalRunOutput;
+    finalRunOutputSource?: "stdout" | "stderr";
     structuredOutputSource?: "stdout" | "stderr";
     structuredOutputDiagnostics?: {
         stdoutJsonObjectCount: number;
@@ -54,6 +58,8 @@ export interface RuntimeExecutionOutput {
         lastStdoutLine?: string;
         lastStderrLine?: string;
         likelyCause: "no_output_from_runtime" | "json_missing" | "json_on_stderr_only" | "schema_or_shape_mismatch";
+        finalRunOutputStatus?: "valid" | "missing" | "malformed" | "schema_mismatch";
+        finalRunOutputError?: string;
         claudeStopReason?: string;
         claudeResultSubtype?: string;
         claudeSessionId?: string;
@@ -94,6 +100,8 @@ export declare function executePromptRuntime(command: string, prompt: string, co
     claudeContract?: ClaudeContractDiagnostics;
 }): Promise<RuntimeExecutionOutput>;
 export declare function containsRateLimitFailure(text: string): boolean;
+export declare function containsUsageLimitHardStopFailure(text: string): boolean;
+export declare function containsProviderUsageLimitFailure(text: string): boolean;
 export declare function checkRuntimeCommandHealth(command: string, options?: {
     cwd?: string;
     timeoutMs?: number;
@@ -117,4 +125,9 @@ export declare function parseGeminiStreamOutput(stdout: string, stderr?: string)
     sessionId?: string;
 } | undefined;
 export declare function parseRuntimeTranscript(provider: LocalProvider | undefined, stdout: string, stderr: string): RuntimeTranscriptEvent[] | undefined;
+export declare function parseAgentFinalRunOutput(text: string): {
+    output?: AgentFinalRunOutput;
+    error?: FinalRunOutputParseError;
+    detail?: string;
+};
 export {};

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

@@ -1,4 +1,4 @@
-import type { ExecutionOutcome, ProviderType } from "bopodev-contracts";
+import type { AgentFinalRunOutput, ExecutionOutcome, ProviderType } from "bopodev-contracts";
 export type AgentProviderType = ProviderType;
 export interface AgentWorkItem {
     issueId: string;
@@ -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;
@@ -88,12 +98,20 @@ export interface AdapterExecutionResult {
     tokenInput: number;
     tokenOutput: number;
     usdCost: number;
+    finalRunOutput?: AgentFinalRunOutput;
     usage?: AdapterNormalizedUsage;
     pricingProviderType?: string | null;
     pricingModelId?: string | null;
     outcome?: ExecutionOutcome;
     nextState?: AgentState;
     trace?: AdapterTrace;
+    dispositionHint?: {
+        kind: "provider_usage_limited";
+        persistStatus: "skipped";
+        pauseAgent: boolean;
+        notifyBoard: boolean;
+        message: string;
+    };
 }
 export interface AgentAdapter {
     providerType: AgentProviderType;