The open-source agent harness - the runtime layer that turns an LLM into a working agent.
Disallow undefined in capability state values.
debajyoti-truefoundry16cfc17978a3
diff --git a/packages/harness/src/agent-session/store/ISessionStore.ts b/packages/harness/src/agent-session/store/ISessionStore.tsindex d82f3a685..1533818ce 100644--- a/packages/harness/src/agent-session/store/ISessionStore.ts+++ b/packages/harness/src/agent-session/store/ISessionStore.ts@@ -2,6 +2,7 @@ import type { MCPServerInitInfo, ThreadOverwriteContextEvent } from '../../core/import type { CompletionUsage } from '../../core/llm/LLMTypes';import type {AgentThreadSnapshot,+ CapabilityStateValue,ContextMessage,SubAgentCompletionMarker,} from '../../core/runtime/AgentThread.types';@@ -123,7 +124,7 @@ export interface PatchThreadCapabilityStateInput {turn_id: string;thread_id: string;key: string;- state: unknown;+ state: CapabilityStateValue;}export interface ListTurnEventsInput {diff --git a/packages/harness/src/core/capabilities/AgentCapability.ts b/packages/harness/src/core/capabilities/AgentCapability.tsindex 8cfbe0065..b35b64420 100644--- a/packages/harness/src/core/capabilities/AgentCapability.ts+++ b/packages/harness/src/core/capabilities/AgentCapability.ts@@ -1,5 +1,6 @@import type { InstructionBuilder } from '../InstructionBuilder';import type { IToolSet } from '../mcp/IMCPServer';+import type { CapabilityStateValue } from '../runtime/AgentThread.types';import type {PostToolCallAgentContextProcessor,PreLLMAgentContextProcessor,@@ -21,5 +22,5 @@ export interface AgentCapability {* thread (`tfy.` reserved for builtins). `load` hydrates from the previous* turn's capability_state; writes go through CAPABILITY_STATE events.*/- readonly state?: { key: string; load(state: unknown): void };+ readonly state?: { key: string; load(state: CapabilityStateValue): void };}diff --git a/packages/harness/src/core/index.ts b/packages/harness/src/core/index.tsindex ed169b459..1d0fe7aa7 100644--- a/packages/harness/src/core/index.ts+++ b/packages/harness/src/core/index.ts@@ -116,7 +116,12 @@ export type {ThreadOverwriteContextEvent,} from './events/schema';export { InternalEventType } from './runtime/AgentThread.types';-export type { AgentThreadSendBatch, ContextMessage } from './runtime/AgentThread.types';+export type {+ AgentThreadSendBatch,+ CapabilityState,+ CapabilityStateValue,+ ContextMessage,+} from './runtime/AgentThread.types';export type { AgentThreadMetrics } from './runtime/metrics';// Tracingdiff --git a/packages/harness/src/core/runtime/AgentThread.ts b/packages/harness/src/core/runtime/AgentThread.tsindex 9cfd7bac4..bb842a3b5 100644--- a/packages/harness/src/core/runtime/AgentThread.ts+++ b/packages/harness/src/core/runtime/AgentThread.ts@@ -64,6 +64,7 @@ import type {AgentThreadRuntimeSendBatch,AgentThreadRuntimeSendInput,AgentThreadSnapshot,+ CapabilityState,} from './AgentThread.types';import {InternalEventType,@@ -494,7 +495,7 @@ export class AgentThread {private currentState: AgentThreadState | null = null;private readonly preComputedCompletion?: SubAgentCompletionMarker | undefined;/** Mirrored capability KV — source for toSnapshot().capability_state. */- private capabilityState: Record<string, unknown> = {};+ private capabilityState: CapabilityState = {};private readonly capabilityStateKeys: ReadonlySet<string>;constructor(input: AgentThreadConstructorInput) {@@ -1373,12 +1374,12 @@ function assertUniqueStateKeys(capabilities: readonly AgentCapability[]): void {function claimCapabilityState(capabilities: readonly AgentCapability[],- input: Record<string, unknown> | undefined,+ input: CapabilityState | undefined,logger: Logger,-): Record<string, unknown> {+): CapabilityState {if (!input) return {};const claimedKeys = new Set(capabilities.map(c => c.state?.key).filter((k): k is string => typeof k === 'string'));- const claimed: Record<string, unknown> = {};+ const claimed: CapabilityState = {};for (const [key, value] of Object.entries(input)) {if (!claimedKeys.has(key)) {logger.warn(`Dropping unclaimed capability_state key '${key}' — no capability declares it`);diff --git a/packages/harness/src/core/runtime/AgentThread.types.ts b/packages/harness/src/core/runtime/AgentThread.types.tsindex 16cfb70cb..1176c88cc 100644--- a/packages/harness/src/core/runtime/AgentThread.types.ts+++ b/packages/harness/src/core/runtime/AgentThread.types.ts@@ -49,6 +49,16 @@ export const InternalEventType = {CAPABILITY_STATE: 'internal.capability.state',} as const;+/**+ * JSON-serializable capability state value. Excludes `undefined` — durability is+ * jsonb/JSON, so clears use `null` and absent data omits the key or the map.+ */+export type CapabilityStateValue =+ null | boolean | number | string | CapabilityStateValue[] | { [key: string]: CapabilityStateValue };++/** Cross-turn capability KV map. Keys: capability.state.key; `tfy.` reserved for builtins. */+export type CapabilityState = Record<string, CapabilityStateValue>;+/*** Cross-turn capability KV write. Processors emit without `thread_id`* ({@link AgentContextProcessorOutput}); AgentThread stamps `thread_id` when yielding.@@ -57,7 +67,7 @@ export interface InternalCapabilityStateEvent {type: typeof InternalEventType.CAPABILITY_STATE;thread_id: string;key: string;- state: unknown;+ state: CapabilityStateValue;}export interface InternalPassthroughEvent {@@ -161,7 +171,7 @@ export interface AgentThreadSnapshot {agent_info?: AgentInfo | undefined;completion?: SubAgentCompletionMarker | undefined;/** Cross-turn capability KV. Keys: capability.state.key; `tfy.` reserved for builtins. */- capability_state?: Record<string, unknown> | undefined;+ capability_state?: CapabilityState | undefined;}export interface AgentThreadConstructorInput {@@ -179,7 +189,7 @@ export interface AgentThreadConstructorInput {* Previous turn's capability_state for hydration. Optional — omit on first* turn / fresh sub-agent. The constructor is the sole hydration site.*/- capabilityState?: Record<string, unknown> | undefined;+ capabilityState?: CapabilityState | undefined;tracing: AgentTracing;logger: Logger;}diff --git a/packages/harness/tests/agent-session/capabilityState.test.ts b/packages/harness/tests/agent-session/capabilityState.test.tsindex e918e5ad5..8e02599c3 100644--- a/packages/harness/tests/agent-session/capabilityState.test.ts+++ b/packages/harness/tests/agent-session/capabilityState.test.ts@@ -10,18 +10,14 @@ import { InMemorySessionStore } from '../../src/agent-session/store/InMemorySessimport type { AgentCapability } from '../../src/core/capabilities/AgentCapability';import type { AgentContextProcessorOutput } from '../../src/core/capabilities/AgentContextProcessor';import { AgentThread } from '../../src/core/runtime/AgentThread';-import { InternalEventType } from '../../src/core/runtime/AgentThread.types';+import { InternalEventType, type CapabilityStateValue } from '../../src/core/runtime/AgentThread.types';import { NOOP_AGENT_TRACING } from '../../src/core/tracing/NoopAgentTracing';import { emptyLlmStream, makeAgentSpec, makeMockILLM, makeSilentLogger, makeTestResolver } from './testHelpers';-interface PlanState {- todo: { title: string; description: string; status: string }[];-}-function makePlanShapedCapability(options: {enabled: boolean;- emitState?: PlanState;- onLoad?: (state: unknown) => void;+ emitState?: CapabilityStateValue;+ onLoad?: (state: CapabilityStateValue) => void;}): AgentCapability {const emitState = options.emitState;const processor = {@@ -41,7 +37,7 @@ function makePlanShapedCapability(options: {preLLMProcessors: [processor],state: {key: 'tfy.plan',- load(state: unknown) {+ load(state: CapabilityStateValue) {options.onLoad?.(state);},},@@ -62,10 +58,10 @@ describe('capability_state (tfy.plan fixture)', () => {agent_spec: makeAgentSpec(),});- const planV1: PlanState = {+ const planV1: CapabilityStateValue = {todo: [{ title: 'step', description: 'do it', status: 'wip' }],};- let loads: unknown[] = [];+ let loads: CapabilityStateValue[] = [];const turn1 = await session.createTurn({input: [{ type: EventType.USER_MESSAGE, content: 'start' }],@@ -132,7 +128,7 @@ describe('capability_state (tfy.plan fixture)', () => {session_id: 's1',agent_spec: makeAgentSpec(),});- const planV1: PlanState = {+ const planV1: CapabilityStateValue = {todo: [{ title: 'step', description: 'do it', status: 'done' }],};