zeitlich 0.2.51 → 0.2.53

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeitlich",
-  "version": "0.2.51",
+  "version": "0.2.53",
   "description": "[EXPERIMENTAL] An opinionated AI agent implementation for Temporal",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -181,7 +181,7 @@
     "node": ">=18"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.100.1",
+    "@anthropic-ai/sdk": "^0.102.0",
     "@aws-sdk/client-s3": "^3.1000.0",
     "@aws-sdk/lib-storage": "^3.1000.0",
     "@daytonaio/sdk": "^0.184.0",

package/src/lib/hooks/index.ts

@@ -3,6 +3,8 @@ export type {
   SessionStartHook,
   SessionEndHookContext,
   SessionEndHook,
+  TurnCompleteHookContext,
+  TurnCompleteHook,
   PreHumanMessageAppendHookContext,
   PreHumanMessageAppendHook,
   PostHumanMessageAppendHookContext,

package/src/lib/hooks/types.ts

@@ -1,4 +1,4 @@
-import type { SessionExitReason } from "../types";
+import type { SessionExitReason, TokenUsage } from "../types";
 import type { ToolMap, ToolRouterHooks } from "../tool-router/types";
 
 // ============================================================================
@@ -29,6 +29,7 @@ export interface SessionEndHookContext {
   agentName: string;
   exitReason: SessionExitReason;
   turns: number;
+  usage: TokenUsage;
   metadata: Record<string, unknown>;
 }
 
@@ -39,6 +40,28 @@ export type SessionEndHook = (
   ctx: SessionEndHookContext
 ) => void | Promise<void>;
 
+/**
+ * Context for TurnComplete hook - called after each agent turn commits
+ * (i.e. once per model invocation, excluding rewound turns)
+ */
+export interface TurnCompleteHookContext {
+  threadId: string;
+  agentName: string;
+  /** 1-based turn number that just completed */
+  turn: number;
+  /** Number of tool calls the model requested this turn */
+  toolCallCount: number;
+  /** Token usage reported by the model for this turn, if available */
+  usage?: TokenUsage;
+}
+
+/**
+ * TurnComplete hook - called after each agent turn commits
+ */
+export type TurnCompleteHook = (
+  ctx: TurnCompleteHookContext
+) => void | Promise<void>;
+
 // ============================================================================
 // Message Lifecycle Hooks
 // ============================================================================
@@ -95,4 +118,6 @@ export interface Hooks<
   onSessionStart?: SessionStartHook;
   /** Called when session ends */
   onSessionEnd?: SessionEndHook;
+  /** Called after each agent turn commits (excludes rewound turns) */
+  onTurnComplete?: TurnCompleteHook;
 }

package/src/lib/observability/hooks.ts

@@ -1,6 +1,10 @@
 import { proxySinks } from "@temporalio/workflow";
 import type { ZeitlichObservabilitySinks } from "./sinks";
-import type { SessionStartHook, SessionEndHook } from "../hooks/types";
+import type {
+  SessionStartHook,
+  SessionEndHook,
+  TurnCompleteHook,
+} from "../hooks/types";
 import type {
   PostToolUseHook,
   PostToolUseFailureHook,
@@ -9,6 +13,7 @@ import type {
 export interface ObservabilityHooks {
   onSessionStart: SessionStartHook;
   onSessionEnd: SessionEndHook;
+  onTurnComplete: TurnCompleteHook;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   onPostToolUse: PostToolUseHook<any, any>;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -58,11 +63,21 @@ export function createObservabilityHooks(
         threadId: ctx.threadId,
         exitReason: ctx.exitReason,
         turns: ctx.turns,
-        usage: {},
+        usage: ctx.usage,
         durationMs: Date.now() - sessionStartMs,
       });
     },
 
+    onTurnComplete: (ctx) => {
+      zeitlichMetrics.turnCompleted({
+        agentName,
+        threadId: ctx.threadId,
+        turn: ctx.turn,
+        toolCallCount: ctx.toolCallCount,
+        ...(ctx.usage && { usage: ctx.usage }),
+      });
+    },
+
     onPostToolUse: (ctx) => {
       zeitlichMetrics.toolExecuted({
         agentName,

package/src/lib/session/session.ts

@@ -4,7 +4,7 @@ import {
   ApplicationFailure,
   log,
 } from "@temporalio/workflow";
-import type { SessionExitReason } from "../types";
+import type { SessionExitReason, TokenUsage } from "../types";
 import type { SessionConfig, ZeitlichSession } from "./types";
 import { resolveSessionLifecycle } from "./types";
 import type {
@@ -232,7 +232,8 @@ export async function createSession<
 
   const callSessionEnd = async (
     exitReason: SessionExitReason,
-    turns: number
+    turns: number,
+    usage: TokenUsage
   ): Promise<void> => {
     if (hooks.onSessionEnd) {
       await hooks.onSessionEnd({
@@ -240,6 +241,7 @@ export async function createSession<
         agentName,
         exitReason,
         turns,
+        usage,
         metadata,
       });
     }
@@ -554,6 +556,15 @@ export async function createSession<
           });
 
           if (!toolRouter.hasTools() || rawToolCalls.length === 0) {
+            if (hooks.onTurnComplete) {
+              await hooks.onTurnComplete({
+                threadId,
+                agentName,
+                turn: currentTurn,
+                toolCallCount: rawToolCalls.length,
+                ...(usage && { usage }),
+              });
+            }
             stateManager.complete();
             exitReason = "completed";
             finalMessage = message;
@@ -638,6 +649,16 @@ export async function createSession<
 
           // Turn committed: fresh id for the next turn.
           assistantId = undefined;
+
+          if (hooks.onTurnComplete) {
+            await hooks.onTurnComplete({
+              threadId,
+              agentName,
+              turn: currentTurn,
+              toolCallCount: rawToolCalls.length,
+              ...(usage && { usage }),
+            });
+          }
         }
 
         if (stateManager.getTurns() >= maxTurns && stateManager.isRunning()) {
@@ -707,7 +728,14 @@ export async function createSession<
           });
         }
 
-        await callSessionEnd(exitReason, stateManager.getTurns());
+        const totals = stateManager.getTotalUsage();
+        await callSessionEnd(exitReason, totals.turns, {
+          inputTokens: totals.totalInputTokens,
+          outputTokens: totals.totalOutputTokens,
+          cachedWriteTokens: totals.totalCachedWriteTokens,
+          cachedReadTokens: totals.totalCachedReadTokens,
+          reasonTokens: totals.totalReasonTokens,
+        });
 
         if (sandboxOwned && sandboxId && sandboxOps) {
           switch (resolvedShutdown) {

package/src/lib/state/types.ts

@@ -29,19 +29,17 @@ export type JsonValue =
  * Rejects: functions, symbols, undefined, class instances with methods
  */
 export type JsonSerializable<T> = {
-  [K in keyof T]: T[K] extends JsonValue
-    ? T[K]
-    : T[K] extends JsonPrimitive
-      ? T[K]
-      : T[K] extends (infer U)[]
-        ? U extends JsonValue
-          ? T[K]
-          : JsonSerializable<U>[]
-        : T[K] extends object
-          ? JsonSerializable<T[K]>
-          : never;
+  [K in keyof T]: JsonSerializableValue<T[K]>;
 };
 
+type JsonSerializableValue<V> = V extends JsonValue
+  ? V
+  : V extends (infer U)[]
+    ? JsonSerializableValue<U>[]
+    : V extends object
+      ? JsonSerializable<V>
+      : never;
+
 /**
  * Full state type combining base state with custom state
  */

package/src/workflow.ts

@@ -116,6 +116,8 @@ export type {
   SessionStartHookContext,
   SessionEndHook,
   SessionEndHookContext,
+  TurnCompleteHook,
+  TurnCompleteHookContext,
   PreHumanMessageAppendHook,
   PreHumanMessageAppendHookContext,
   PostHumanMessageAppendHook,