Agent harness sessions and results

How a native session binds to an OpenClaw session and mirrors into its transcript, and how tool, media, terminal-outcome, and settled-turn results come back through the attempt result. Part of the Agent harness plugins reference.

Native sessions and transcript mirror

A harness may keep a native session id, thread id, or daemon-side resume token. Keep that binding explicitly associated with the OpenClaw session, and keep mirroring user-visible assistant/tool output into the OpenClaw transcript.

The OpenClaw transcript remains the compatibility layer for:

• channel-visible session history
• transcript search and indexing
• switching back to the built-in OpenClaw harness on a later turn
• generic /new, /reset, and session deletion behavior

For user-message mirrors, use restorePreparedUserTurnOperationalMetaForRuntime({ runtimeMessage, preparedMessage }) from openclaw/plugin-sdk/agent-harness-runtime. Pass an independent, trusted snapshot of the host-prepared input as preparedMessage. Clone content and selected-mention metadata before hooks that can mutate them in place, and keep that snapshot unchanged.

The helper restores operational metadata on user messages without replacing native or hook-rewritten content. Non-user runtime messages are returned unchanged. Human mentions survive only when the entire content value exactly matches the prepared snapshot; changed text must not inherit the old selections.

Restored metadata neither authorizes actions nor proves a fresh transcript append. After the canonical append, pass its committed message, anchor, and actual { appended } result to userTurnTranscriptRecorder.markRuntimePersisted(...). Only appended: true can trigger an original-input commit notification; an idempotent history match must report false.

Store native bindings in plugin state. Implement reset(...) for an in-place session reset and withSessionDeletion(params, run) for removal of a session key, including expiry and maintenance. A physical session ID changing at the same key is a transfer, not deletion; preserve any compaction adoption path.

Core logs reset-hook failures once per harness ID per process, including across plugin reloads. Later resets still invoke the hook so it can recover.

ACPX automatically migrates sessions from its former <workspace>/state default to /acpx when the new default is empty. Set plugins.entries.acpx.config.stateDir only to keep a different location; explicit values are never relocated. Failed adoption warns and retains the old location for the process so an update does not silently hide existing sessions.

withSessionDeletion acquires the native owner's lease before calling run({ commit, rollback }). Core invokes the synchronous commit() at the session row deletion boundary and rollback() if the transaction fails. Rollback must also tolerate a failed or unapplied commit. Keep asynchronous subscription cleanup after run so it does not hold the SQLite writer queue; do not restore bindings for errors after the session transaction committed.

Recheck params.assertCurrent() after awaited work and immediately before mutating native state. The callback belongs to one registered harness lifetime; retaining it after the operation closes does not retain authority. Post-delete hooks are notifications, not the owner of durable binding removal.

Implement withSessionContextReset(params, run) when a native binding must be invalidated by a successful same-key rewind or branch switch. This optional hook uses the same prepared commit/rollback contract, but keeps the session key and retained history. Core commits invalidation only after validating the requested cut and restores it if the transcript transaction fails. Release subscriptions after the committed mutation settles. The optional previousSessionId is the recorded predecessor, allowing retirement of a binding not yet transferred after compaction without adopting it during preparation. Ordinary compaction does not invoke this hook and continues to preserve native thread continuity.

Shared native binding lifecycle

Official harnesses use the JavaScript-only private openclaw/plugin-sdk/agent-harness-session-runtime; it is not a third-party Plugin SDK contract. Binding mutations use action-bound plugin-state observations and conditional writes in the shared-state worker. Durable bundled session deletion and conditional rollback settle in the executing agent worker. Synchronous reads still serve native lease assertions; opaque released deletion callbacks, incognito sessions, and message-cut transactions keep their existing native ownership. createNativeSessionBindingLifecycle owns exact-token lease acquisition, renewal, mutation fences, and transactional deletion/rollback. The backend supplies matching synchronous and asynchronous views of the same plugin-state namespace, its record codec, acquisition/retention policy, errors, and timing. Pass host authority through assertCurrent and validate the expected generation in assertRecordCurrent. Leases coordinate storage; they grant no execution authority. Keep native cleanup after the host transaction commits.

Inside withLease, call captureLeaseAssertion(key) to capture the exact owner and recheck its live, unexpired lease before native requests or transcript writes. Combine it with host authority for normal work. Cleanup may use retained lease ownership after host retirement, but must reject an expired, replaced, or closed lease even while the harness remains alive.

captureNativeSessionGenerationAuthority, reclaimNativeSessionGeneration, and resolveNativeSessionBinding preserve the host generation and predecessor across waits, adopting a verified predecessor before stale reclamation. A missing host entry permits an ephemeral session; a failed read cannot authorize a binding.

createNativeSessionInitializationOwner associates binding and upstream-link writes with the exact host creation handle. Rollback requires the matching store, identity, binding, and live authority, removes only the exact upstream link, then invokes backend cleanup. Queue selection, native protocol/policy, and resource cleanup remain with the backend; core owns host session lifecycle.

Tool and media results

Same-turn retry context

The optional params.continuation carries host-owned recovery context when a transient failure retries the same task. Its prompt is the original current request; its messages contains settled attempt snapshots in order, including completed assistant/tool messages and tool results. Keep the request visible outside bounded history projections and retain completed tool evidence when rendering the snapshots. These facts describe completed work; they do not grant execution authority or ask the harness to execute those tools again.

Codex consumes this carrier even when the admission-fenced transcript ends before the current request, using its existing bounded context projection. The continuation instruction stays model-only and is not persisted as another user turn. Harnesses that ignore the optional field retain their existing transcript-based recovery behavior.

inferToolMetaFromArgs from openclaw/plugin-sdk/agent-harness-runtime returns compact, lossy display metadata. Array values deeper than 64 levels are omitted; shallower siblings still contribute to the preview. The helper can return undefined. Keep the original arguments for validation and execution: display metadata is neither an argument replacement nor a general-purpose traversal limit.

Core constructs the OpenClaw tool list and passes it into the prepared attempt. When a harness executes a dynamic tool call, return the tool result back through the harness result shape instead of sending channel media yourself.

This keeps text, image, video, music, TTS, approval, and messaging-tool outputs on the same delivery path as OpenClaw-backed runs.

For messaging tools, read the original result's details.messageDelivery with readEmbeddedMessageDeliveryFact from openclaw/plugin-sdk/agent-harness-runtime. Only settled delivery counts as a sent message; successful dry runs and suppressed sends must not suppress a later reply. Preserve partial delivery evidence when a tool also reports an error. Messaging tool results without a delivery fact use isDeliveredMessagingToolResult, which owns tool eligibility and receipt interpretation. For core conversation tools, it reads the original Gateway result's details.status: sent confirms delivery, as do replied and timeout for conversations_turn. A peer-reply timeout or correlation error does not undo the channel send or change the tool's error status. queued, suppressed, and unknown do not confirm delivery, even when they include a prepared message ID. Session coordination results are not external delivery receipts. Use requirePluginDeliveryId: true when legacy plugin results need a concrete message ID; authoritative core conversation statuses do not require one. projectPluginMessageDeliveryFact reads legacy result envelopes into the shared delivery shape, retaining partial-delivery status for attachment handling. For legacy message sends, an error takes precedence over a message ID unless the result confirms partial delivery. Use isDeliveredMessagingToolSendToCurrentSource for source-route comparisons and extractMessagingToolSourceReplyPayload to retain attachment metadata and the transcript owner's confirmation. Presentation middleware cannot establish new delivery facts.

The same runtime entrypoint exports sanitizeToolArgs for diagnostic tool arguments and event payloads. It redacts nested fields without mutating the input and preserves own JSON keys, including __proto__; repeated references become "[Circular]". Use sanitizeToolResult for result presentation, which also applies the shared result-size and image-storage rules.

For successful sessions_spawn results, use normalizeAcceptedSessionSpawnResult from openclaw/plugin-sdk/agent-harness-tool-runtime and retain its AcceptedSessionSpawn in the attempt's acceptedSessionSpawns. Capture the original result before middleware changes its details. Preserve expectsCompletionMessage: core needs that fact to transfer child completion delivery when the requester yields. The helper returns null for an unaccepted or incomplete receipt and treats missing completion intent as false.

Set AgentHarnessAttemptResult.hostOwnedToolMediaUrls only for native artifacts that the trusted harness runtime created and persisted itself. Every entry must also appear in toolMediaUrls. Never include model-selected dynamic-tool or OpenClaw-tool media. On message_tool_only routes, this narrow provenance lets native runtime artifacts survive source-reply suppression; normal send policy and ambient-room admission still apply.

Harness delivery defaults

Set deliveryDefaults.visibleReplies to "automatic" or "message_tool" when a harness needs a default visible-reply policy. Explicit message config still takes precedence.

The deprecated sourceVisibleReplies field remains supported for published harness plugins, including July 2026 versions of @openclaw/codex. When both fields are present, visibleReplies takes precedence. Plugin authors should migrate to that field. The October 1 removal date does not retire a contract while supported published plugins still produce it.

Terminal tool outcomes

AgentHarnessAttemptParams.observeToolTerminal is the host-owned terminal outcome accumulator. A harness that executes OpenClaw dynamic tools or native tools must call it when each tool reaches one terminal outcome, before the attempt result is finalized. Harnesses that do not execute tools do not need to call it.

Report facts from the execution boundary:

• Pass the protocol call id when one exists, the canonical tool name, and the arguments that actually reached the tool after preparation or hook rewrites.
• Pass the original host tool result or thrown error as result. Core reads private effect provenance from that object; serialized fields cannot provide this proof. Preserve internal result state when projecting a host result.
• Set executionStarted: false when validation, approval, or another guard stopped the call before the tool implementation began. Once dispatch may have happened, report true conservatively.
• Report outcome: "success" or outcome: "failure". Include the structured failure fields available from the runtime instead of inferring failure from display text.
• Use nativeMutation only for native tools that do not use an OpenClaw tool definition. Supply protocol-owned mutation and replay facts there; do not copy OpenClaw's mutation classifier into the harness.

The callback returns the canonical resolution for that call. Carry its lastToolError into AgentHarnessAttemptResult and use its execution, arguments, and side-effect facts in the harness projection instead of deriving parallel state. The host keeps an unresolved mutating failure across unrelated successful tools and clears it only after the matching action succeeds.

The callback remains optional for source compatibility with older experimental harnesses. Optional does not mean ignorable for a harness that executes tools: without terminal reports, OpenClaw cannot preserve mutating-tool failure truth across later tool calls, including quiet heartbeat completion.

Settled tool finalization

OpenClaw may need one final visible answer after a harness has completed every tool call but its native turn ended without assistant text. A harness can opt into that recovery by implementing finalizeSettledTurn({ attempt, settledAttempt }).

The callback is a separate capability, not another ordinary attempt. It must:

• use either the exact restricted native transcript or a complete application transcript frozen through the settled tool-result boundary;
• expose no tools, permission-grant or user-input capabilities, native execution hooks, agents, skills, memory, scheduling, extensions, or remote control;
• send only the host-provided finalization prompt; and
• fail closed if its selected transcript/isolation strategy cannot enforce those restrictions.

OpenClaw invokes the callback once as a terminal sub-operation, outside the ordinary attempt and retry loop. A failure ends the run with the side-effect-aware incomplete-turn warning; it cannot enter ordinary auth/profile rotation, model fallback, context recovery, compaction continuation, or hook-requested revision paths. Finalization also skips plugin prompt mutation, before_agent_run, LLM input/output, terminal revision, and agent_end hooks. Core diagnostics still record the operation and its failure.

The callback returns AgentHarnessSettledTurnFinalizationResult, not an ordinary attempt result. Its public fields are limited to the completed assistant message, finalization-call usage, transcript-ownership metadata, and diagnostic trace. Tool, delivery, media, spawn, lifecycle, replay, session, and fallback state cannot cross this result boundary. Unknown fields and assistant tool calls fail closed.

A harness that internally reuses its full attempt engine can call projectSettledTurnFinalizationAttemptResult(...) before returning. The helper rejects canonical failure, tool, delivery, replay, and lifecycle evidence, then projects only the narrow result. It is defense in depth after native isolation, not a substitute for removing the native capability surface.

A projection-backed harness must capture the active branch after the settled turn is mirrored and prove that the current prompt and every current tool call/result are present through that boundary. Put the frozen evidence on settledAttempt.settledTurnFinalizationContext as one of:

• source: "openclaw-transcript" with messages: the complete application transcript through the boundary.
• source: "harness" with data: an immutable, bounded projection interpreted only by the owning harness. Core passes this opaque value through; the finalizer must verify its own context type before using it.
• source: "unavailable": the harness permits finalization for this settled turn, but safe replay evidence could not be captured. The finalizer must reject this state before provider or native I/O; core can still use its existing host-owned fallback without repeating tools.

The unavailable state records eligibility, not validated history. Eligible capture failures, including missing, drifting, or oversized evidence, can reach that no-model fallback. Do not emit it for failures the harness excludes from finalization, such as authentication or usage-limit errors. Command-only harnesses must retain the attributed assistant tool-call entry in messagesSnapshot; the host fallback can use that settled-batch identity when visible-assistant fields are absent.

Enforce projection limits while acquiring messages, rather than cloning the whole transcript before checking its size. Successful capture must finish all identity and source-evidence checks before returning the attempt. Do not retain an open transcript reader in data. The finalizer must reject a missing, unsupported, ambiguous, or oversized context. It must not truncate messages, drop earlier history, or describe an application projection as exact native history. Harnesses that resume one restricted native session do not need this projection field.

Do not implement this callback by calling runAttempt with a best-effort disableTools hint. The harness owner must enforce the complete native capability boundary. OpenClaw does not provide a generic fallback because it cannot attest that an arbitrary native runtime honored those restrictions.

The callback remains optional for experimental third-party harness compatibility. When the selected harness omits it, OpenClaw preserves the existing incomplete-turn error instead of risking repeated side effects.