liuyu/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-06-06 05:51:15 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: document agent harness sdk contracts

Browse Source
This commit is contained in:
Peter Steinberger
2026-06-04 22:45:30 -04:00
parent 9448f91e6f
commit 8f6e71087b
2 changed files with 13 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
src/plugin-sdk/agent-harness-runtime.ts
View File

@@ -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"]
>;

6
src/plugin-sdk/agent-harness-task-runtime.ts
View File

@@ -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>
>;