From 8f6e71087b01182e9e308038939ce8ea20e82dbb Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 22:45:30 -0400
Subject: [PATCH] docs: document agent harness sdk contracts

---
 src/plugin-sdk/agent-harness-runtime.ts      | 10 +++++++---
 src/plugin-sdk/agent-harness-task-runtime.ts |  6 ++++++
 2 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/src/plugin-sdk/agent-harness-runtime.ts b/src/plugin-sdk/agent-harness-runtime.ts
index f822142748ff..6f256a805bf8 100644
--- a/src/plugin-sdk/agent-harness-runtime.ts
+++ b/src/plugin-sdk/agent-harness-runtime.ts
@@ -24,6 +24,7 @@ import { redactToolDetail } from "../logging/redact.js";
 import type { PromptImageOrderEntry } from "../media/prompt-image-order.js";
 import { truncateUtf16Safe } from "../utils.js";
 
+/** Default truncation limit for user-facing tool progress output. */
 export const TOOL_PROGRESS_OUTPUT_MAX_CHARS = 8_000;
 
 export type { AgentMessage } from "../agents/runtime/index.js";
@@ -154,9 +155,7 @@ export {
   resolveActiveEmbeddedRunSessionId,
   setActiveEmbeddedRun,
 };
-export type {
-  AbortAndDrainEmbeddedAgentRunResult as AbortAndDrainAgentHarnessRunResult,
-};
+export type { AbortAndDrainEmbeddedAgentRunResult as AbortAndDrainAgentHarnessRunResult };
 
 /**
  * @deprecated Active-run queueing is an internal runtime concern. This legacy
@@ -190,6 +189,7 @@ export type {
 } from "../agents/codex-mcp-config.types.js";
 export { normalizeProviderToolSchemas } from "../agents/embedded-agent-runner/tool-schema-runtime.js";
 
+/** Detect prompt image references and load them through the same limits used by embedded runs. */
 export async function detectAndLoadAgentHarnessPromptImages(params: {
   prompt: string;
   workspaceDir: string;
@@ -227,6 +227,7 @@ export async function detectAndLoadAgentHarnessPromptImages(params: {
   });
 }
 
+/** Load Codex bundle MCP thread config without forcing the heavy config module into SDK imports. */
 export async function loadCodexBundleMcpThreadConfig(
   params: LoadCodexBundleMcpThreadConfigParams,
 ): Promise<CodexBundleMcpThreadConfig> {
@@ -331,6 +332,7 @@ export {
  */
 export type ToolProgressDetailMode = "explain" | "raw";
 
+/** Infer compact display metadata for one tool invocation from its name and arguments. */
 export function inferToolMetaFromArgs(
   toolName: string,
   args: unknown,
@@ -359,6 +361,7 @@ export function formatToolProgressOutput(
   return `${truncateUtf16Safe(redacted, maxChars)}\n...(truncated)...`;
 }
 
+/** Inputs used to classify a finished harness turn with little or no visible assistant output. */
 export type AgentHarnessTerminalOutcomeInput = {
   assistantTexts: readonly string[];
   reasoningText?: string | null;
@@ -367,6 +370,7 @@ export type AgentHarnessTerminalOutcomeInput = {
   turnCompleted: boolean;
 };
 
+/** Terminal fallback classification emitted by agent harness adapters. */
 export type AgentHarnessTerminalOutcomeClassification = NonNullable<
   EmbeddedRunAttemptResult["agentHarnessResultClassification"]
 >;
diff --git a/src/plugin-sdk/agent-harness-task-runtime.ts b/src/plugin-sdk/agent-harness-task-runtime.ts
index bd7f2cb660c0..5ce171b9c502 100644
--- a/src/plugin-sdk/agent-harness-task-runtime.ts
+++ b/src/plugin-sdk/agent-harness-task-runtime.ts
@@ -48,6 +48,7 @@ export type AgentHarnessTaskRuntimeScopeParams = {
   runIdPrefix?: string;
 };
 
+/** Create-task params with runtime and requester scope supplied by the scoped task runtime. */
 export type AgentHarnessScopedCreateRunningTaskRunParams = Omit<
   CreateRunningTaskRunParams,
   "runtime" | "taskKind" | "requesterSessionKey" | "ownerKey" | "scopeKind"
@@ -55,16 +56,19 @@ export type AgentHarnessScopedCreateRunningTaskRunParams = Omit<
   runId: string;
 };
 
+/** Progress params scoped to the requester session owned by the harness runtime. */
 export type AgentHarnessScopedRecordTaskRunProgressParams = Omit<
   RecordTaskRunProgressParams,
   "runtime" | "sessionKey"
 >;
 
+/** Finalization params scoped to the requester session owned by the harness runtime. */
 export type AgentHarnessScopedFinalizeTaskRunParams = Omit<
   FinalizeTaskRunParams,
   "runtime" | "sessionKey"
 >;
 
+/** Delivery-status params scoped to the requester session owned by the harness runtime. */
 export type AgentHarnessScopedSetDeliveryStatusParams = Omit<
   SetDeliveryStatusParams,
   "runtime" | "sessionKey"
@@ -82,8 +86,10 @@ export type AgentHarnessTaskRuntime = {
   listTaskRecords(): TaskRecord[];
 };
 
+/** Completion states a harness task can report to its requester. */
 export type AgentHarnessCompletionStatus = "succeeded" | "failed" | "cancelled";
 
+/** Delivery result returned after routing a harness task completion announcement. */
 export type AgentHarnessCompletionDelivery = Awaited<
   ReturnType<typeof deliverSubagentAnnouncement>
 >;