Skip to content

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.ts
index 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.ts
index 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.ts
index 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';
// Tracing
diff --git a/packages/harness/src/core/runtime/AgentThread.ts b/packages/harness/src/core/runtime/AgentThread.ts
index 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.ts
index 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.ts
index 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/InMemorySess
import 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' }],
};