Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

feat: Add a event schema with paused/running status (#785)

Srajan Asthanabd67d567508b
diff --git a/.changeset/turn-update-event.md b/.changeset/turn-update-event.md
new file mode 100644
index 000000000..583eb4ac3
--- /dev/null
+++ b/.changeset/turn-update-event.md
@@ -0,0 +1,7 @@
+---
+"@truefoundry/trueforge-core": patch
+"@truefoundry/trueforge": patch
+"@truefoundry/trueforge-ui": patch
+---
+
+Add a `turn.update` event schema with paused/running status and `action_required_on_events`.
diff --git a/.github/fern/openapi/openapi.json b/.github/fern/openapi/openapi.json
index 4e1f73d07..099c6d695 100644
--- a/.github/fern/openapi/openapi.json
+++ b/.github/fern/openapi/openapi.json
@@ -2,6 +2,18 @@
"components": {
"parameters": {},
"schemas": {
+ "ActionRequired": {
+ "properties": {
+ "id": {
+ "description": "Unique identifier for the event (monotonic ULID).",
+ "type": "string"
+ }
+ },
+ "required": [
+ "id"
+ ],
+ "type": "object"
+ },
"ActionRequiredEvent": {
"discriminator": {
"mapping": {
@@ -4024,7 +4036,8 @@
"tool.response": "#/components/schemas/ToolResponseEvent",
"tool.response_required": "#/components/schemas/ToolResponseRequiredEvent",
"turn.created": "#/components/schemas/TurnCreatedEvent",
- "turn.done": "#/components/schemas/TurnDoneEvent"
+ "turn.done": "#/components/schemas/TurnDoneEvent",
+ "turn.update": "#/components/schemas/TurnUpdateEvent"
},
"propertyName": "type"
},
@@ -4032,6 +4045,9 @@
{
"$ref": "#/components/schemas/TurnCreatedEvent"
},
+ {
+ "$ref": "#/components/schemas/TurnUpdateEvent"
+ },
{
"$ref": "#/components/schemas/TurnDoneEvent"
},
@@ -5379,7 +5395,8 @@
"tool.response": "#/components/schemas/ToolResponseEvent",
"tool.response_required": "#/components/schemas/ToolResponseRequiredEvent",
"turn.created": "#/components/schemas/TurnCreatedEvent",
- "turn.done": "#/components/schemas/TurnDoneEvent"
+ "turn.done": "#/components/schemas/TurnDoneEvent",
+ "turn.update": "#/components/schemas/TurnUpdateEvent"
},
"propertyName": "type"
},
@@ -5417,11 +5434,107 @@
{
"$ref": "#/components/schemas/TurnCreatedEvent"
},
+ {
+ "$ref": "#/components/schemas/TurnUpdateEvent"
+ },
{
"$ref": "#/components/schemas/TurnDoneEvent"
}
]
},
+ "TurnUpdateEvent": {
+ "properties": {
+ "created_at": {
+ "description": "ISO 8601 event timestamp.",
+ "type": "string"
+ },
+ "id": {
+ "description": "Unique identifier for the event (monotonic ULID).",
+ "type": "string"
+ },
+ "state": {
+ "$ref": "#/components/schemas/TurnUpdateState"
+ },
+ "thread_id": {
+ "description": "Thread that owns the event; null for turn-level lifecycle events.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "type": {
+ "description": "Emitted when a turn pauses or resumes.",
+ "enum": [
+ "turn.update"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "id",
+ "state",
+ "created_at",
+ "thread_id"
+ ],
+ "type": "object"
+ },
+ "TurnUpdateState": {
+ "description": "Live non-terminal turn status.",
+ "discriminator": {
+ "mapping": {
+ "paused": "#/components/schemas/TurnUpdateStatePaused",
+ "running": "#/components/schemas/TurnUpdateStateRunning"
+ },
+ "propertyName": "status"
+ },
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/TurnUpdateStatePaused"
+ },
+ {
+ "$ref": "#/components/schemas/TurnUpdateStateRunning"
+ }
+ ]
+ },
+ "TurnUpdateStatePaused": {
+ "properties": {
+ "action_required_on_events": {
+ "description": "Events that still need a user or client action.",
+ "items": {
+ "$ref": "#/components/schemas/ActionRequired"
+ },
+ "type": "array"
+ },
+ "status": {
+ "description": "Turn is paused waiting for required actions.",
+ "enum": [
+ "paused"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "status",
+ "action_required_on_events"
+ ],
+ "type": "object"
+ },
+ "TurnUpdateStateRunning": {
+ "properties": {
+ "status": {
+ "description": "Turn is executing.",
+ "enum": [
+ "running"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "status"
+ ],
+ "type": "object"
+ },
"UpdateAgentRequest": {
"additionalProperties": false,
"properties": {
diff --git a/docs/openapi.json b/docs/openapi.json
index 4e1f73d07..099c6d695 100644
--- a/docs/openapi.json
+++ b/docs/openapi.json
@@ -2,6 +2,18 @@
"components": {
"parameters": {},
"schemas": {
+ "ActionRequired": {
+ "properties": {
+ "id": {
+ "description": "Unique identifier for the event (monotonic ULID).",
+ "type": "string"
+ }
+ },
+ "required": [
+ "id"
+ ],
+ "type": "object"
+ },
"ActionRequiredEvent": {
"discriminator": {
"mapping": {
@@ -4024,7 +4036,8 @@
"tool.response": "#/components/schemas/ToolResponseEvent",
"tool.response_required": "#/components/schemas/ToolResponseRequiredEvent",
"turn.created": "#/components/schemas/TurnCreatedEvent",
- "turn.done": "#/components/schemas/TurnDoneEvent"
+ "turn.done": "#/components/schemas/TurnDoneEvent",
+ "turn.update": "#/components/schemas/TurnUpdateEvent"
},
"propertyName": "type"
},
@@ -4032,6 +4045,9 @@
{
"$ref": "#/components/schemas/TurnCreatedEvent"
},
+ {
+ "$ref": "#/components/schemas/TurnUpdateEvent"
+ },
{
"$ref": "#/components/schemas/TurnDoneEvent"
},
@@ -5379,7 +5395,8 @@
"tool.response": "#/components/schemas/ToolResponseEvent",
"tool.response_required": "#/components/schemas/ToolResponseRequiredEvent",
"turn.created": "#/components/schemas/TurnCreatedEvent",
- "turn.done": "#/components/schemas/TurnDoneEvent"
+ "turn.done": "#/components/schemas/TurnDoneEvent",
+ "turn.update": "#/components/schemas/TurnUpdateEvent"
},
"propertyName": "type"
},
@@ -5417,11 +5434,107 @@
{
"$ref": "#/components/schemas/TurnCreatedEvent"
},
+ {
+ "$ref": "#/components/schemas/TurnUpdateEvent"
+ },
{
"$ref": "#/components/schemas/TurnDoneEvent"
}
]
},
+ "TurnUpdateEvent": {
+ "properties": {
+ "created_at": {
+ "description": "ISO 8601 event timestamp.",
+ "type": "string"
+ },
+ "id": {
+ "description": "Unique identifier for the event (monotonic ULID).",
+ "type": "string"
+ },
+ "state": {
+ "$ref": "#/components/schemas/TurnUpdateState"
+ },
+ "thread_id": {
+ "description": "Thread that owns the event; null for turn-level lifecycle events.",
+ "type": [
+ "string",
+ "null"
+ ]
+ },
+ "type": {
+ "description": "Emitted when a turn pauses or resumes.",
+ "enum": [
+ "turn.update"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "type",
+ "id",
+ "state",
+ "created_at",
+ "thread_id"
+ ],
+ "type": "object"
+ },
+ "TurnUpdateState": {
+ "description": "Live non-terminal turn status.",
+ "discriminator": {
+ "mapping": {
+ "paused": "#/components/schemas/TurnUpdateStatePaused",
+ "running": "#/components/schemas/TurnUpdateStateRunning"
+ },
+ "propertyName": "status"
+ },
+ "oneOf": [
+ {
+ "$ref": "#/components/schemas/TurnUpdateStatePaused"
+ },
+ {
+ "$ref": "#/components/schemas/TurnUpdateStateRunning"
+ }
+ ]
+ },
+ "TurnUpdateStatePaused": {
+ "properties": {
+ "action_required_on_events": {
+ "description": "Events that still need a user or client action.",
+ "items": {
+ "$ref": "#/components/schemas/ActionRequired"
+ },
+ "type": "array"
+ },
+ "status": {
+ "description": "Turn is paused waiting for required actions.",
+ "enum": [
+ "paused"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "status",
+ "action_required_on_events"
+ ],
+ "type": "object"
+ },
+ "TurnUpdateStateRunning": {
+ "properties": {
+ "status": {
+ "description": "Turn is executing.",
+ "enum": [
+ "running"
+ ],
+ "type": "string"
+ }
+ },
+ "required": [
+ "status"
+ ],
+ "type": "object"
+ },
"UpdateAgentRequest": {
"additionalProperties": false,
"properties": {
diff --git a/packages/trueforge-core/src/agent-session/index.ts b/packages/trueforge-core/src/agent-session/index.ts
index ce973db0a..3b9b5d66c 100644
--- a/packages/trueforge-core/src/agent-session/index.ts
+++ b/packages/trueforge-core/src/agent-session/index.ts
@@ -47,6 +47,7 @@ export {
SessionEventSchema,
TurnCreatedEventSchema,
TurnDoneEventSchema,
+ TurnUpdateEventSchema,
} from './schemas/events';
export type {
PersistedTurnEvent,
@@ -54,6 +55,7 @@ export type {
SessionEventItem,
TurnCreatedEvent,
TurnDoneEvent,
+ TurnUpdateEvent,
} from './schemas/events';
export { TokenPaginationSchema } from './schemas/pagination';
diff --git a/packages/trueforge-core/src/agent-session/schemas/events.ts b/packages/trueforge-core/src/agent-session/schemas/events.ts
index 9bdf31df7..370f209c2 100644
--- a/packages/trueforge-core/src/agent-session/schemas/events.ts
+++ b/packages/trueforge-core/src/agent-session/schemas/events.ts
@@ -1,7 +1,8 @@
/**
* Turn/session event product schemas. Event payloads come from the harness; this
- * module owns turn lifecycle events (turn.created / turn.done) and the persisted
- * event unions the store writes. SSE streaming envelopes stay in server/schemas.
+ * module owns turn lifecycle events (turn.created / turn.update / turn.done) and
+ * the persisted event unions the store writes. SSE streaming envelopes stay in
+ * server/schemas.
*/
import { z } from '@hono/zod-openapi';
import type { WithRegisteredPassthrough } from '../../core/events/PassthroughEvents';
@@ -30,6 +31,7 @@ import {
export const EventType = {
...HarnessEventType,
TURN_CREATED: 'turn.created',
+ TURN_UPDATE: 'turn.update',
TURN_DONE: 'turn.done',
} as const;
@@ -58,10 +60,47 @@ export const TurnDoneEventSchema = z
})
.openapi('TurnDoneEvent');
+export const ActionRequiredSchema = z
+ .object({
+ id: EventIdSchema,
+ })
+ .openapi('ActionRequired');
+
+export const TurnUpdateStatePausedSchema = z
+ .object({
+ status: z.literal('paused').describe('Turn is paused waiting for required actions.'),
+ action_required_on_events: z
+ .array(ActionRequiredSchema)
+ .describe('Events that still need a user or client action.'),
+ })
+ .openapi('TurnUpdateStatePaused');
+
+export const TurnUpdateStateRunningSchema = z
+ .object({
+ status: z.literal('running').describe('Turn is executing.'),
+ })
+ .openapi('TurnUpdateStateRunning');
+
+export const TurnUpdateStateSchema = z
+ .discriminatedUnion('status', [TurnUpdateStatePausedSchema, TurnUpdateStateRunningSchema])
+ .describe('Live non-terminal turn status.')
+ .openapi('TurnUpdateState');
+
+export const TurnUpdateEventSchema = z
+ .object({
+ type: z.literal(EventType.TURN_UPDATE).describe('Emitted when a turn pauses or resumes.'),
+ id: EventIdSchema,
+ state: TurnUpdateStateSchema,
+ created_at: z.string().describe('ISO 8601 event timestamp.'),
+ thread_id: z.string().nullable().describe('Thread that owns the event; null for turn-level lifecycle events.'),
+ })
+ .openapi('TurnUpdateEvent');
+
/** Built-in durable turn events — lifecycle + content; no deltas, no passthrough. */
export const SessionEventSchema = z
.discriminatedUnion('type', [
TurnCreatedEventSchema,
+ TurnUpdateEventSchema,
TurnDoneEventSchema,
ModelMessageEventSchema,
ToolResponseEventSchema,
@@ -84,6 +123,7 @@ export const SessionEventItemSchema = z
.openapi('SessionEventItem');
export type TurnCreatedEvent = z.infer<typeof TurnCreatedEventSchema>;
+export type TurnUpdateEvent = z.infer<typeof TurnUpdateEventSchema>;
export type TurnDoneEvent = z.infer<typeof TurnDoneEventSchema>;
export type SessionEvent = z.infer<typeof SessionEventSchema>;
/**
diff --git a/packages/trueforge-sdk/src/api/types/ActionRequired.ts b/packages/trueforge-sdk/src/api/types/ActionRequired.ts
new file mode 100644
index 000000000..caa583aaf
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/ActionRequired.ts
@@ -0,0 +1,6 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export interface ActionRequired {
+ /** Unique identifier for the event (monotonic ULID). */
+ id: string;
+}
diff --git a/packages/trueforge-sdk/src/api/types/SessionEvent.ts b/packages/trueforge-sdk/src/api/types/SessionEvent.ts
index 7595b8969..8d305b279 100644
--- a/packages/trueforge-sdk/src/api/types/SessionEvent.ts
+++ b/packages/trueforge-sdk/src/api/types/SessionEvent.ts
@@ -13,4 +13,5 @@ export type SessionEvent =
| TrueForge.ToolResponseEvent
| TrueForge.ToolResponseRequiredEvent
| TrueForge.TurnCreatedEvent
- | TrueForge.TurnDoneEvent;
+ | TrueForge.TurnDoneEvent
+ | TrueForge.TurnUpdateEvent;
diff --git a/packages/trueforge-sdk/src/api/types/TurnStreamingEvent.ts b/packages/trueforge-sdk/src/api/types/TurnStreamingEvent.ts
index 0c706540c..61f6515ac 100644
--- a/packages/trueforge-sdk/src/api/types/TurnStreamingEvent.ts
+++ b/packages/trueforge-sdk/src/api/types/TurnStreamingEvent.ts
@@ -14,4 +14,5 @@ export type TurnStreamingEvent =
| TrueForge.ToolResponseEvent
| TrueForge.ToolResponseRequiredEvent
| TrueForge.TurnCreatedEvent
- | TrueForge.TurnDoneEvent;
+ | TrueForge.TurnDoneEvent
+ | TrueForge.TurnUpdateEvent;
diff --git a/packages/trueforge-sdk/src/api/types/TurnUpdateEvent.ts b/packages/trueforge-sdk/src/api/types/TurnUpdateEvent.ts
new file mode 100644
index 000000000..3b6bf0f46
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/TurnUpdateEvent.ts
@@ -0,0 +1,14 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../index.js";
+
+export interface TurnUpdateEvent {
+ /** ISO 8601 event timestamp. */
+ createdAt: string;
+ /** Unique identifier for the event (monotonic ULID). */
+ id: string;
+ state: TrueForge.TurnUpdateState;
+ /** Thread that owns the event; null for turn-level lifecycle events. */
+ threadId: string | null;
+ type: "turn.update";
+}
diff --git a/packages/trueforge-sdk/src/api/types/TurnUpdateState.ts b/packages/trueforge-sdk/src/api/types/TurnUpdateState.ts
new file mode 100644
index 000000000..86c4d0e0e
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/TurnUpdateState.ts
@@ -0,0 +1,8 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../index.js";
+
+/**
+ * Live non-terminal turn status.
+ */
+export type TurnUpdateState = TrueForge.TurnUpdateStatePaused | TrueForge.TurnUpdateStateRunning;
diff --git a/packages/trueforge-sdk/src/api/types/TurnUpdateStatePaused.ts b/packages/trueforge-sdk/src/api/types/TurnUpdateStatePaused.ts
new file mode 100644
index 000000000..6610360e2
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/TurnUpdateStatePaused.ts
@@ -0,0 +1,9 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../index.js";
+
+export interface TurnUpdateStatePaused {
+ /** Events that still need a user or client action. */
+ actionRequiredOnEvents: TrueForge.ActionRequired[];
+ status: "paused";
+}
diff --git a/packages/trueforge-sdk/src/api/types/TurnUpdateStateRunning.ts b/packages/trueforge-sdk/src/api/types/TurnUpdateStateRunning.ts
new file mode 100644
index 000000000..bb4be8e7f
--- /dev/null
+++ b/packages/trueforge-sdk/src/api/types/TurnUpdateStateRunning.ts
@@ -0,0 +1,5 @@
+// This file was auto-generated by Fern from our API Definition.
+
+export interface TurnUpdateStateRunning {
+ status: "running";
+}
diff --git a/packages/trueforge-sdk/src/api/types/index.ts b/packages/trueforge-sdk/src/api/types/index.ts
index 53ded384c..9b29138b5 100644
--- a/packages/trueforge-sdk/src/api/types/index.ts
+++ b/packages/trueforge-sdk/src/api/types/index.ts
@@ -1,3 +1,4 @@
+export * from "./ActionRequired.js";
export * from "./ActionRequiredEvent.js";
export * from "./Agent.js";
export * from "./AgentCodeSnippet.js";
@@ -222,6 +223,10 @@ export * from "./TurnStateError.js";
export * from "./TurnStateErrorMetrics.js";
export * from "./TurnStateRunning.js";
export * from "./TurnStreamingEvent.js";
+export * from "./TurnUpdateEvent.js";
+export * from "./TurnUpdateState.js";
+export * from "./TurnUpdateStatePaused.js";
+export * from "./TurnUpdateStateRunning.js";
export * from "./UserMessage.js";
export * from "./UserMessageContent.js";
export * from "./UserMessageContentItem.js";
diff --git a/packages/trueforge-sdk/src/serialization/types/ActionRequired.ts b/packages/trueforge-sdk/src/serialization/types/ActionRequired.ts
new file mode 100644
index 000000000..1356bbbfe
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/ActionRequired.ts
@@ -0,0 +1,16 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+
+export const ActionRequired: core.serialization.ObjectSchema<serializers.ActionRequired.Raw, TrueForge.ActionRequired> =
+ core.serialization.object({
+ id: core.serialization.string(),
+ });
+
+export declare namespace ActionRequired {
+ export interface Raw {
+ id: string;
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/SessionEvent.ts b/packages/trueforge-sdk/src/serialization/types/SessionEvent.ts
index eac3fed26..bd14830f2 100644
--- a/packages/trueforge-sdk/src/serialization/types/SessionEvent.ts
+++ b/packages/trueforge-sdk/src/serialization/types/SessionEvent.ts
@@ -14,6 +14,7 @@ import { ToolResponseEvent } from "./ToolResponseEvent.js";
import { ToolResponseRequiredEvent } from "./ToolResponseRequiredEvent.js";
import { TurnCreatedEvent } from "./TurnCreatedEvent.js";
import { TurnDoneEvent } from "./TurnDoneEvent.js";
+import { TurnUpdateEvent } from "./TurnUpdateEvent.js";
export const SessionEvent: core.serialization.Schema<serializers.SessionEvent.Raw, TrueForge.SessionEvent> =
core.serialization.undiscriminatedUnion([
@@ -28,6 +29,7 @@ export const SessionEvent: core.serialization.Schema<serializers.SessionEvent.Ra
ToolResponseRequiredEvent,
TurnCreatedEvent,
TurnDoneEvent,
+ TurnUpdateEvent,
]);
export declare namespace SessionEvent {
@@ -42,5 +44,6 @@ export declare namespace SessionEvent {
| ToolResponseEvent.Raw
| ToolResponseRequiredEvent.Raw
| TurnCreatedEvent.Raw
- | TurnDoneEvent.Raw;
+ | TurnDoneEvent.Raw
+ | TurnUpdateEvent.Raw;
}
diff --git a/packages/trueforge-sdk/src/serialization/types/TurnStreamingEvent.ts b/packages/trueforge-sdk/src/serialization/types/TurnStreamingEvent.ts
index f823e40d7..29756a573 100644
--- a/packages/trueforge-sdk/src/serialization/types/TurnStreamingEvent.ts
+++ b/packages/trueforge-sdk/src/serialization/types/TurnStreamingEvent.ts
@@ -15,6 +15,7 @@ import { ToolResponseEvent } from "./ToolResponseEvent.js";
import { ToolResponseRequiredEvent } from "./ToolResponseRequiredEvent.js";
import { TurnCreatedEvent } from "./TurnCreatedEvent.js";
import { TurnDoneEvent } from "./TurnDoneEvent.js";
+import { TurnUpdateEvent } from "./TurnUpdateEvent.js";
export const TurnStreamingEvent: core.serialization.Schema<
serializers.TurnStreamingEvent.Raw,
@@ -32,6 +33,7 @@ export const TurnStreamingEvent: core.serialization.Schema<
ToolResponseRequiredEvent,
TurnCreatedEvent,
TurnDoneEvent,
+ TurnUpdateEvent,
]);
export declare namespace TurnStreamingEvent {
@@ -47,5 +49,6 @@ export declare namespace TurnStreamingEvent {
| ToolResponseEvent.Raw
| ToolResponseRequiredEvent.Raw
| TurnCreatedEvent.Raw
- | TurnDoneEvent.Raw;
+ | TurnDoneEvent.Raw
+ | TurnUpdateEvent.Raw;
}
diff --git a/packages/trueforge-sdk/src/serialization/types/TurnUpdateEvent.ts b/packages/trueforge-sdk/src/serialization/types/TurnUpdateEvent.ts
new file mode 100644
index 000000000..84357a566
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/TurnUpdateEvent.ts
@@ -0,0 +1,27 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+import { TurnUpdateState } from "./TurnUpdateState.js";
+
+export const TurnUpdateEvent: core.serialization.ObjectSchema<
+ serializers.TurnUpdateEvent.Raw,
+ TrueForge.TurnUpdateEvent
+> = core.serialization.object({
+ createdAt: core.serialization.property("created_at", core.serialization.string()),
+ id: core.serialization.string(),
+ state: TurnUpdateState,
+ threadId: core.serialization.property("thread_id", core.serialization.string().nullable()),
+ type: core.serialization.stringLiteral("turn.update"),
+});
+
+export declare namespace TurnUpdateEvent {
+ export interface Raw {
+ created_at: string;
+ id: string;
+ state: TurnUpdateState.Raw;
+ thread_id?: string | null;
+ type: "turn.update";
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/TurnUpdateState.ts b/packages/trueforge-sdk/src/serialization/types/TurnUpdateState.ts
new file mode 100644
index 000000000..d6f59a863
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/TurnUpdateState.ts
@@ -0,0 +1,14 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+import { TurnUpdateStatePaused } from "./TurnUpdateStatePaused.js";
+import { TurnUpdateStateRunning } from "./TurnUpdateStateRunning.js";
+
+export const TurnUpdateState: core.serialization.Schema<serializers.TurnUpdateState.Raw, TrueForge.TurnUpdateState> =
+ core.serialization.undiscriminatedUnion([TurnUpdateStatePaused, TurnUpdateStateRunning]);
+
+export declare namespace TurnUpdateState {
+ export type Raw = TurnUpdateStatePaused.Raw | TurnUpdateStateRunning.Raw;
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/TurnUpdateStatePaused.ts b/packages/trueforge-sdk/src/serialization/types/TurnUpdateStatePaused.ts
new file mode 100644
index 000000000..9642f6075
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/TurnUpdateStatePaused.ts
@@ -0,0 +1,24 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+import { ActionRequired } from "./ActionRequired.js";
+
+export const TurnUpdateStatePaused: core.serialization.ObjectSchema<
+ serializers.TurnUpdateStatePaused.Raw,
+ TrueForge.TurnUpdateStatePaused
+> = core.serialization.object({
+ actionRequiredOnEvents: core.serialization.property(
+ "action_required_on_events",
+ core.serialization.list(ActionRequired),
+ ),
+ status: core.serialization.stringLiteral("paused"),
+});
+
+export declare namespace TurnUpdateStatePaused {
+ export interface Raw {
+ action_required_on_events: ActionRequired.Raw[];
+ status: "paused";
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/TurnUpdateStateRunning.ts b/packages/trueforge-sdk/src/serialization/types/TurnUpdateStateRunning.ts
new file mode 100644
index 000000000..426582c85
--- /dev/null
+++ b/packages/trueforge-sdk/src/serialization/types/TurnUpdateStateRunning.ts
@@ -0,0 +1,18 @@
+// This file was auto-generated by Fern from our API Definition.
+
+import type * as TrueForge from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+
+export const TurnUpdateStateRunning: core.serialization.ObjectSchema<
+ serializers.TurnUpdateStateRunning.Raw,
+ TrueForge.TurnUpdateStateRunning
+> = core.serialization.object({
+ status: core.serialization.stringLiteral("running"),
+});
+
+export declare namespace TurnUpdateStateRunning {
+ export interface Raw {
+ status: "running";
+ }
+}
diff --git a/packages/trueforge-sdk/src/serialization/types/index.ts b/packages/trueforge-sdk/src/serialization/types/index.ts
index 53ded384c..9b29138b5 100644
--- a/packages/trueforge-sdk/src/serialization/types/index.ts
+++ b/packages/trueforge-sdk/src/serialization/types/index.ts
@@ -1,3 +1,4 @@
+export * from "./ActionRequired.js";
export * from "./ActionRequiredEvent.js";
export * from "./Agent.js";
export * from "./AgentCodeSnippet.js";
@@ -222,6 +223,10 @@ export * from "./TurnStateError.js";
export * from "./TurnStateErrorMetrics.js";
export * from "./TurnStateRunning.js";
export * from "./TurnStreamingEvent.js";
+export * from "./TurnUpdateEvent.js";
+export * from "./TurnUpdateState.js";
+export * from "./TurnUpdateStatePaused.js";
+export * from "./TurnUpdateStateRunning.js";
export * from "./UserMessage.js";
export * from "./UserMessageContent.js";
export * from "./UserMessageContentItem.js";
diff --git a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/chatServer.ts b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/chatServer.ts
index c011102bb..f2839e3e6 100644
--- a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/chatServer.ts
+++ b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/chatServer.ts
@@ -129,9 +129,13 @@ export interface HarnessPageSource<T> {
export function toListResult<TSource, TResult>(
page: HarnessPageSource<TSource>,
- map: (item: TSource) => TResult,
+ map: (item: TSource) => TResult | undefined,
): ListResult<TResult> {
- const data = page.data.map(map);
+ const data: TResult[] = [];
+ for (const item of page.data) {
+ const mapped = map(item);
+ if (mapped !== undefined) data.push(mapped);
+ }
const token = page.response.pagination.nextPageToken;
return {
data,
@@ -237,10 +241,13 @@ export function createHarnessChatServer(
});
let fallbackSequence = 0;
for await (const item of stream.withMetadata()) {
- yield {
- sequenceNumber: sequenceNumber(item.id, fallbackSequence),
- event: toUiStreamingEvent(item.data),
- };
+ const event = toUiStreamingEvent(item.data);
+ if (event !== undefined) {
+ yield {
+ sequenceNumber: sequenceNumber(item.id, fallbackSequence),
+ event,
+ };
+ }
fallbackSequence += 1;
}
},
@@ -260,10 +267,13 @@ export function createHarnessChatServer(
});
let fallbackSequence = 0;
for await (const item of stream.withMetadata()) {
- yield {
- sequenceNumber: sequenceNumber(item.id, fallbackSequence),
- event: toUiStreamingEvent(item.data),
- };
+ const event = toUiStreamingEvent(item.data);
+ if (event !== undefined) {
+ yield {
+ sequenceNumber: sequenceNumber(item.id, fallbackSequence),
+ event,
+ };
+ }
fallbackSequence += 1;
}
},
diff --git a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/toUiTurnState.ts b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/toUiTurnState.ts
index 3eda956b5..afc837de0 100644
--- a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/toUiTurnState.ts
+++ b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/toUiTurnState.ts
@@ -35,16 +35,21 @@ function toUiTerminalTurnState(state: TrueForgeApi.TurnDoneEventState): Exclude<
}
}
-export function toUiSessionEvent(event: TrueForgeApi.SessionEvent): SessionEventItem['event'] {
+export function toUiSessionEvent(event: TrueForgeApi.SessionEvent): SessionEventItem['event'] | undefined {
+ // TODO: map turn.update when the runtime event union includes it
+ if (event.type === 'turn.update') return undefined;
if (event.type !== 'turn.done') return { ...event };
return { ...event, state: toUiTerminalTurnState(event.state) };
}
-export function toUiStreamingEvent(event: TrueForgeApi.TurnStreamingEvent): TurnStreamingEvent {
+export function toUiStreamingEvent(event: TrueForgeApi.TurnStreamingEvent): TurnStreamingEvent | undefined {
+ // TODO: map turn.update when the runtime event union includes it
+ if (event.type === 'turn.update') return undefined;
if (event.type !== 'turn.done') return { ...event };
return { ...event, state: toUiTerminalTurnState(event.state) };
}
-export function toUiEventItem(item: TrueForgeApi.SessionEventItem): SessionEventItem {
- return { turnId: item.turnId, event: toUiSessionEvent(item.event) };
+export function toUiEventItem(item: TrueForgeApi.SessionEventItem): SessionEventItem | undefined {
+ const event = toUiSessionEvent(item.event);
+ return event === undefined ? undefined : { turnId: item.turnId, event };
}
diff --git a/packages/trueforge/src/schemas/events.ts b/packages/trueforge/src/schemas/events.ts
index 41e13d080..4b702a6e1 100644
--- a/packages/trueforge/src/schemas/events.ts
+++ b/packages/trueforge/src/schemas/events.ts
@@ -9,6 +9,7 @@ import {
TokenPaginationSchema,
TurnCreatedEventSchema,
TurnDoneEventSchema,
+ TurnUpdateEventSchema,
} from '@truefoundry/trueforge-core/agent-session';
import {
MCPAuthRequiredEventSchema,
@@ -41,6 +42,7 @@ export const TurnStreamingEventSchema = z
ToolApprovalRequiredEventSchema,
ToolResponseRequiredEventSchema,
TurnCreatedEventSchema,
+ TurnUpdateEventSchema,
TurnDoneEventSchema,
])
.openapi('TurnStreamingEvent');
diff --git a/python/trueforge_sdk/src/trueforge_sdk/__init__.py b/python/trueforge_sdk/src/trueforge_sdk/__init__.py
index 8ce5e6e85..7242c3c63 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/__init__.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/__init__.py
@@ -7,6 +7,7 @@ from importlib import import_module
if typing.TYPE_CHECKING:
from .types import (
+ ActionRequired,
ActionRequiredEvent,
Agent,
AgentCodeSnippet,
@@ -231,6 +232,10 @@ if typing.TYPE_CHECKING:
TurnStateErrorMetrics,
TurnStateRunning,
TurnStreamingEvent,
+ TurnUpdateEvent,
+ TurnUpdateState,
+ TurnUpdateStatePaused,
+ TurnUpdateStateRunning,
UserMessage,
UserMessageContent,
UserMessageContentItem,
@@ -259,6 +264,7 @@ if typing.TYPE_CHECKING:
from .client import AsyncTrueForge, TrueForge
from .version import __version__
_dynamic_imports: typing.Dict[str, str] = {
+ "ActionRequired": ".types",
"ActionRequiredEvent": ".types",
"Agent": ".types",
"AgentCodeSnippet": ".types",
@@ -497,6 +503,10 @@ _dynamic_imports: typing.Dict[str, str] = {
"TurnStateErrorMetrics": ".types",
"TurnStateRunning": ".types",
"TurnStreamingEvent": ".types",
+ "TurnUpdateEvent": ".types",
+ "TurnUpdateState": ".types",
+ "TurnUpdateStatePaused": ".types",
+ "TurnUpdateStateRunning": ".types",
"UnauthorizedError": ".errors",
"UnprocessableEntityError": ".errors",
"UserMessage": ".types",
@@ -544,6 +554,7 @@ def __dir__():
__all__ = [
+ "ActionRequired",
"ActionRequiredEvent",
"Agent",
"AgentCodeSnippet",
@@ -782,6 +793,10 @@ __all__ = [
"TurnStateErrorMetrics",
"TurnStateRunning",
"TurnStreamingEvent",
+ "TurnUpdateEvent",
+ "TurnUpdateState",
+ "TurnUpdateStatePaused",
+ "TurnUpdateStateRunning",
"UnauthorizedError",
"UnprocessableEntityError",
"UserMessage",
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py b/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py
index 940d2b96a..2e83715b6 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/__init__.py
@@ -6,6 +6,7 @@ import typing
from importlib import import_module
if typing.TYPE_CHECKING:
+ from .action_required import ActionRequired
from .action_required_event import ActionRequiredEvent
from .agent import Agent
from .agent_code_snippet import AgentCodeSnippet
@@ -230,6 +231,10 @@ if typing.TYPE_CHECKING:
from .turn_state_error_metrics import TurnStateErrorMetrics
from .turn_state_running import TurnStateRunning
from .turn_streaming_event import TurnStreamingEvent
+ from .turn_update_event import TurnUpdateEvent
+ from .turn_update_state import TurnUpdateState
+ from .turn_update_state_paused import TurnUpdateStatePaused
+ from .turn_update_state_running import TurnUpdateStateRunning
from .user_message import UserMessage
from .user_message_content import UserMessageContent
from .user_message_content_item import UserMessageContentItem
@@ -239,6 +244,7 @@ if typing.TYPE_CHECKING:
from .web_search_config import WebSearchConfig
from .zai_model_provider import ZaiModelProvider
_dynamic_imports: typing.Dict[str, str] = {
+ "ActionRequired": ".action_required",
"ActionRequiredEvent": ".action_required_event",
"Agent": ".agent",
"AgentCodeSnippet": ".agent_code_snippet",
@@ -463,6 +469,10 @@ _dynamic_imports: typing.Dict[str, str] = {
"TurnStateErrorMetrics": ".turn_state_error_metrics",
"TurnStateRunning": ".turn_state_running",
"TurnStreamingEvent": ".turn_streaming_event",
+ "TurnUpdateEvent": ".turn_update_event",
+ "TurnUpdateState": ".turn_update_state",
+ "TurnUpdateStatePaused": ".turn_update_state_paused",
+ "TurnUpdateStateRunning": ".turn_update_state_running",
"UserMessage": ".user_message",
"UserMessageContent": ".user_message_content",
"UserMessageContentItem": ".user_message_content_item",
@@ -496,6 +506,7 @@ def __dir__():
__all__ = [
+ "ActionRequired",
"ActionRequiredEvent",
"Agent",
"AgentCodeSnippet",
@@ -720,6 +731,10 @@ __all__ = [
"TurnStateErrorMetrics",
"TurnStateRunning",
"TurnStreamingEvent",
+ "TurnUpdateEvent",
+ "TurnUpdateState",
+ "TurnUpdateStatePaused",
+ "TurnUpdateStateRunning",
"UserMessage",
"UserMessageContent",
"UserMessageContentItem",
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/action_required.py b/python/trueforge_sdk/src/trueforge_sdk/types/action_required.py
new file mode 100644
index 000000000..586da9d07
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/action_required.py
@@ -0,0 +1,22 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2
+from ..core.unchecked_base_model import UncheckedBaseModel
+
+
+class ActionRequired(UncheckedBaseModel):
+ id: str = pydantic.Field()
+ """
+ Unique identifier for the event (monotonic ULID).
+ """
+
+ if IS_PYDANTIC_V2:
+ model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow") # type: ignore # Pydantic v2
+ else:
+
+ class Config:
+ smart_union = True
+ extra = pydantic.Extra.allow
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/session_event.py b/python/trueforge_sdk/src/trueforge_sdk/types/session_event.py
index 94f737c15..6119fc25c 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/types/session_event.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/session_event.py
@@ -13,6 +13,7 @@ from .tool_response_event import ToolResponseEvent
from .tool_response_required_event import ToolResponseRequiredEvent
from .turn_created_event import TurnCreatedEvent
from .turn_done_event import TurnDoneEvent
+from .turn_update_event import TurnUpdateEvent
SessionEvent = typing.Union[
McpAuthRequiredEvent,
@@ -26,4 +27,5 @@ SessionEvent = typing.Union[
ToolResponseRequiredEvent,
TurnCreatedEvent,
TurnDoneEvent,
+ TurnUpdateEvent,
]
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/turn_streaming_event.py b/python/trueforge_sdk/src/trueforge_sdk/types/turn_streaming_event.py
index be08f0c0a..3570d5ed6 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/types/turn_streaming_event.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/turn_streaming_event.py
@@ -14,6 +14,7 @@ from .tool_response_event import ToolResponseEvent
from .tool_response_required_event import ToolResponseRequiredEvent
from .turn_created_event import TurnCreatedEvent
from .turn_done_event import TurnDoneEvent
+from .turn_update_event import TurnUpdateEvent
TurnStreamingEvent = typing.Union[
McpAuthRequiredEvent,
@@ -28,4 +29,5 @@ TurnStreamingEvent = typing.Union[
ToolResponseRequiredEvent,
TurnCreatedEvent,
TurnDoneEvent,
+ TurnUpdateEvent,
]
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/turn_update_event.py b/python/trueforge_sdk/src/trueforge_sdk/types/turn_update_event.py
new file mode 100644
index 000000000..678d98640
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/turn_update_event.py
@@ -0,0 +1,36 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2
+from ..core.unchecked_base_model import UncheckedBaseModel
+from .turn_update_state import TurnUpdateState
+
+
+class TurnUpdateEvent(UncheckedBaseModel):
+ created_at: str = pydantic.Field()
+ """
+ ISO 8601 event timestamp.
+ """
+
+ id: str = pydantic.Field()
+ """
+ Unique identifier for the event (monotonic ULID).
+ """
+
+ state: TurnUpdateState
+ thread_id: typing.Optional[str] = pydantic.Field(default=None)
+ """
+ Thread that owns the event; null for turn-level lifecycle events.
+ """
+
+ type: typing.Literal["turn.update"] = "turn.update"
+
+ if IS_PYDANTIC_V2:
+ model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow") # type: ignore # Pydantic v2
+ else:
+
+ class Config:
+ smart_union = True
+ extra = pydantic.Extra.allow
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/turn_update_state.py b/python/trueforge_sdk/src/trueforge_sdk/types/turn_update_state.py
new file mode 100644
index 000000000..931194b20
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/turn_update_state.py
@@ -0,0 +1,8 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+from .turn_update_state_paused import TurnUpdateStatePaused
+from .turn_update_state_running import TurnUpdateStateRunning
+
+TurnUpdateState = typing.Union[TurnUpdateStatePaused, TurnUpdateStateRunning]
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/turn_update_state_paused.py b/python/trueforge_sdk/src/trueforge_sdk/types/turn_update_state_paused.py
new file mode 100644
index 000000000..8edcce45f
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/turn_update_state_paused.py
@@ -0,0 +1,25 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2
+from ..core.unchecked_base_model import UncheckedBaseModel
+from .action_required import ActionRequired
+
+
+class TurnUpdateStatePaused(UncheckedBaseModel):
+ action_required_on_events: typing.List[ActionRequired] = pydantic.Field()
+ """
+ Events that still need a user or client action.
+ """
+
+ status: typing.Literal["paused"] = "paused"
+
+ if IS_PYDANTIC_V2:
+ model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow") # type: ignore # Pydantic v2
+ else:
+
+ class Config:
+ smart_union = True
+ extra = pydantic.Extra.allow
diff --git a/python/trueforge_sdk/src/trueforge_sdk/types/turn_update_state_running.py b/python/trueforge_sdk/src/trueforge_sdk/types/turn_update_state_running.py
new file mode 100644
index 000000000..d0b67f00d
--- /dev/null
+++ b/python/trueforge_sdk/src/trueforge_sdk/types/turn_update_state_running.py
@@ -0,0 +1,19 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import typing
+
+import pydantic
+from ..core.pydantic_utilities import IS_PYDANTIC_V2
+from ..core.unchecked_base_model import UncheckedBaseModel
+
+
+class TurnUpdateStateRunning(UncheckedBaseModel):
+ status: typing.Literal["running"] = "running"
+
+ if IS_PYDANTIC_V2:
+ model_config: typing.ClassVar[pydantic.ConfigDict] = pydantic.ConfigDict(extra="allow") # type: ignore # Pydantic v2
+ else:
+
+ class Config:
+ smart_union = True
+ extra = pydantic.Extra.allow