zidane 1.2.0 → 1.3.1

package/README.md

@@ -290,24 +290,40 @@ MCP connections are made lazily on the first `run()` call and reused across subs
 
 ## Sessions
 
-Sessions give an agent persistent identity, message history, and run metadata across multiple calls or restarts.
+Sessions give an agent persistent identity, turn history, and run metadata across multiple calls or restarts. Each message exchange is a `SessionTurn` with its own UUID, enabling real-time multiplayer streaming.
+
+### SessionTurn
+
+Every message in a session is a turn:
+
+```ts
+interface SessionTurn {
+  id: string                      // UUID — generated by store or crypto.randomUUID()
+  role: 'user' | 'assistant' | 'system'
+  content: SessionContentBlock[]  // same format used by providers
+  usage?: TurnUsage               // token usage (assistant turns only)
+  createdAt: number               // timestamp
+}
+```
 
 ### Creating a session
 
+`createSession` is async — stores can generate IDs server-side (e.g. Supabase).
+
 ```ts
 import { createSession, createMemoryStore } from 'zidane/session'
 
 // In-memory (default, no persistence)
-const session = createSession({ id: 'my-session', agentId: 'my-agent' })
+const session = await createSession({ id: 'my-session', agentId: 'my-agent' })
 
 // With a store for persistence
 const store = createMemoryStore()
-const session = createSession({ id: 'my-session', store })
+const session = await createSession({ id: 'my-session', store })
 ```
 
 ### Storage backends
 
-Three built-in stores are available:
+Three built-in stores are available. All implement the full `SessionStore` interface including incremental operations.
 
 ```ts
 import { createMemoryStore, createSqliteStore, createRemoteStore } from 'zidane/session'
@@ -322,6 +338,38 @@ const sqliteStore = createSqliteStore({ path: './sessions.db' })
 const remoteStore = createRemoteStore({ url: 'https://api.example.com/sessions' })
 ```
 
+### SessionStore interface
+
+```ts
+interface SessionStore {
+  // Optional: server-side ID generation
+  generateSessionId?: () => string | Promise<string>
+  generateTurnId?: () => string | Promise<string>
+
+  // Core CRUD
+  load: (sessionId: string) => Promise<SessionData | null>
+  save: (session: SessionData) => Promise<void>
+  delete: (sessionId: string) => Promise<void>
+  list: (filter?) => Promise<string[]>
+
+  // Incremental operations (avoids full re-save)
+  appendTurns: (sessionId: string, turns: SessionTurn[]) => Promise<void>
+  getTurns: (sessionId: string, from?: number, limit?: number) => Promise<SessionTurn[]>
+  updateRun: (sessionId: string, run: SessionRun) => Promise<void>
+  updateStatus: (sessionId: string, status: SessionStatus) => Promise<void>
+}
+```
+
+Custom ID generation lets external databases (e.g. Supabase) provide UUIDs server-side, keeping IDs in sync:
+
+```ts
+const store = createRemoteStore({ url: '...' })
+store.generateTurnId = async () => {
+  const { data } = await supabase.rpc('gen_random_uuid')
+  return data
+}
+```
+
 ### Agent integration
 
 ```ts
@@ -335,6 +383,18 @@ await agent.run({ prompt: 'hello' })
 await session.save() // persist to store
 ```
 
+Turns are persisted incrementally after each agent turn via `appendTurns` — not as a full document save. If the agent crashes mid-run, you still have turns up to the last completed turn.
+
+### Session status
+
+Sessions track their status: `'idle' | 'running' | 'completed' | 'error'`. The agent updates it automatically during runs.
+
+```ts
+session.status // 'idle'
+await agent.run({ prompt: 'go' })
+// idle → running → completed (or error)
+```
+
 ### Session hooks
 
 ```ts
@@ -347,9 +407,9 @@ agent.hooks.hook('session:end', (ctx) => {
   // ctx.status: 'completed' | 'aborted' | 'error'
 })
 
-agent.hooks.hook('session:messages', (ctx) => {
+agent.hooks.hook('session:turns', (ctx) => {
   // ctx.sessionId, ctx.count
-  // fired after each turn (live message sync)
+  // fired after each turn (incremental sync)
 })
 
 agent.hooks.hook('session:save', (ctx) => {
@@ -363,8 +423,6 @@ agent.hooks.hook('session:meta', (ctx) => {
 })
 ```
 
-Messages are synced to the session after every turn, not just at run start/end. If the agent crashes mid-run, you still have messages up to the last completed turn.
-
 ### Restoring a session
 
 ```ts
@@ -390,11 +448,12 @@ agent.hooks.hook('system:before', (ctx) => {
 
 agent.hooks.hook('turn:before', (ctx) => {
   // ctx.turn: turn number
+  // ctx.turnId: UUID for this turn (generated before LLM call)
   // ctx.options: StreamOptions being sent to provider
 })
 
 agent.hooks.hook('turn:after', (ctx) => {
-  // ctx.turn, ctx.usage { input, output }
+  // ctx.turn, ctx.turnId, ctx.usage { input, output }
 })
 
 agent.hooks.hook('agent:done', (ctx) => {
@@ -412,10 +471,13 @@ agent.hooks.hook('agent:abort', () => {
 agent.hooks.hook('stream:text', (ctx) => {
   // ctx.delta: new text chunk
   // ctx.text: accumulated text so far
+  // ctx.turnId: UUID of the turn being streamed
+  // ctx.blockIndex: content block index within the turn
 })
 
 agent.hooks.hook('stream:end', (ctx) => {
   // ctx.text: final complete text
+  // ctx.turnId, ctx.blockIndex
 })
 ```
 

package/dist/{agent-DvZm8U14.d.ts → agent-DxIUxou4.d.ts}

@@ -1,6 +1,6 @@
 import { Hookable } from 'hookable';
 import Anthropic from '@anthropic-ai/sdk';
-import { M as McpServerConfig, d as TurnUsage, b as SessionMessage, C as ChildRunStats, a as AgentStats, A as AgentRunOptions, c as ToolExecutionMode } from './types-4CFQ-6Qu.js';
+import { M as McpServerConfig, e as TurnUsage, b as SessionMessage, C as ChildRunStats, a as AgentStats, A as AgentRunOptions, c as SessionTurn, d as ToolExecutionMode } from './types-CLRMCak3.js';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { Provider, StreamOptions } from './providers.js';
 import { Session } from './session.js';
@@ -168,18 +168,24 @@ interface AgentHooks {
     }) => void;
     'turn:before': (ctx: {
         turn: number;
+        turnId: string;
         options: StreamOptions;
     }) => void;
     'turn:after': (ctx: {
         turn: number;
+        turnId: string;
         usage: TurnUsage;
     }) => void;
     'stream:text': (ctx: {
         delta: string;
         text: string;
+        turnId: string;
+        blockIndex: number;
     }) => void;
     'stream:end': (ctx: {
         text: string;
+        turnId: string;
+        blockIndex: number;
     }) => void;
     'tool:before': (ctx: {
         name: string;
@@ -264,7 +270,7 @@ interface AgentHooks {
         runId: string;
         status: 'completed' | 'aborted' | 'error';
     }) => void;
-    'session:messages': (ctx: {
+    'session:turns': (ctx: {
         sessionId: string;
         count: number;
     }) => void;
@@ -286,7 +292,7 @@ interface AgentOptions {
     execution?: ExecutionContext;
     /** MCP servers to connect and expose as tools */
     mcpServers?: McpServerConfig[];
-    /** Session for identity, message persistence, and run tracking */
+    /** Session for identity, turn persistence, and run tracking */
     session?: Session;
     /** @internal */
     _mcpConnector?: (configs: McpServerConfig[]) => Promise<McpConnection>;
@@ -302,7 +308,7 @@ interface Agent {
     /** Destroy the execution context and clean up resources */
     destroy: () => Promise<void>;
     readonly isRunning: boolean;
-    readonly messages: SessionMessage[];
+    readonly turns: SessionTurn[];
     readonly execution: ExecutionContext;
     readonly handle: ExecutionHandle | null;
     readonly session: Session | null;

package/dist/{chunk-LMSOIIAT.js → chunk-IC2WAUBZ.js}

@@ -21,6 +21,37 @@ function createMemoryStore() {
         ids = ids.slice(0, filter.limit);
       }
       return ids;
+    },
+    async appendTurns(sessionId, turns) {
+      const data = sessions.get(sessionId);
+      if (data) {
+        data.turns.push(...JSON.parse(JSON.stringify(turns)));
+        data.updatedAt = Date.now();
+      }
+    },
+    async getTurns(sessionId, from = 0, limit) {
+      const data = sessions.get(sessionId);
+      if (!data)
+        return [];
+      const sliced = data.turns.slice(from, limit !== void 0 ? from + limit : void 0);
+      return JSON.parse(JSON.stringify(sliced));
+    },
+    async updateRun(sessionId, run) {
+      const data = sessions.get(sessionId);
+      if (data) {
+        const idx = data.runs.findIndex((r) => r.id === run.id);
+        if (idx >= 0) {
+          data.runs[idx] = JSON.parse(JSON.stringify(run));
+        }
+        data.updatedAt = Date.now();
+      }
+    },
+    async updateStatus(sessionId, status) {
+      const data = sessions.get(sessionId);
+      if (data) {
+        data.status = status;
+        data.updatedAt = Date.now();
+      }
     }
   };
 }
@@ -82,6 +113,50 @@ function createRemoteStore(options) {
       }
       const body = await res.json();
       return body.ids;
+    },
+    async appendTurns(sessionId, turns) {
+      const res = await request(`/sessions/${encodeURIComponent(sessionId)}/turns`, {
+        method: "POST",
+        body: JSON.stringify(turns)
+      });
+      if (!res.ok) {
+        throw new Error(`Remote appendTurns failed: ${res.status} ${res.statusText}`);
+      }
+    },
+    async getTurns(sessionId, from = 0, limit) {
+      const params = new URLSearchParams();
+      if (from)
+        params.set("from", String(from));
+      if (limit !== void 0)
+        params.set("limit", String(limit));
+      const query = params.toString();
+      const path = `/sessions/${encodeURIComponent(sessionId)}/turns${query ? `?${query}` : ""}`;
+      const res = await request(path);
+      if (!res.ok) {
+        throw new Error(`Remote getTurns failed: ${res.status} ${res.statusText}`);
+      }
+      return await res.json();
+    },
+    async updateRun(sessionId, run) {
+      const res = await request(
+        `/sessions/${encodeURIComponent(sessionId)}/runs/${encodeURIComponent(run.id)}`,
+        {
+          method: "PUT",
+          body: JSON.stringify(run)
+        }
+      );
+      if (!res.ok) {
+        throw new Error(`Remote updateRun failed: ${res.status} ${res.statusText}`);
+      }
+    },
+    async updateStatus(sessionId, status) {
+      const res = await request(`/sessions/${encodeURIComponent(sessionId)}`, {
+        method: "PATCH",
+        body: JSON.stringify({ status })
+      });
+      if (!res.ok) {
+        throw new Error(`Remote updateStatus failed: ${res.status} ${res.statusText}`);
+      }
     }
   };
 }
@@ -113,7 +188,7 @@ function createSqliteStore(options) {
   const stmtDelete = db.prepare("DELETE FROM sessions WHERE id = ?");
   const stmtList = db.prepare("SELECT id FROM sessions ORDER BY updated_at DESC");
   const stmtListByAgent = db.prepare("SELECT id FROM sessions WHERE agent_id = ? ORDER BY updated_at DESC");
-  return {
+  const store = {
     async load(sessionId) {
       const row = stmtLoad.get(sessionId);
       if (!row)
@@ -144,19 +219,61 @@ function createSqliteStore(options) {
         return ids.slice(0, filter.limit);
       }
       return ids;
+    },
+    async appendTurns(sessionId, turns) {
+      const data = await store.load(sessionId);
+      if (data) {
+        data.turns.push(...turns);
+        data.updatedAt = Date.now();
+        await store.save(data);
+      }
+    },
+    async getTurns(sessionId, from = 0, limit) {
+      const data = await store.load(sessionId);
+      if (!data)
+        return [];
+      return data.turns.slice(from, limit !== void 0 ? from + limit : void 0);
+    },
+    async updateRun(sessionId, run) {
+      const data = await store.load(sessionId);
+      if (data) {
+        const idx = data.runs.findIndex((r) => r.id === run.id);
+        if (idx >= 0) {
+          data.runs[idx] = run;
+        }
+        data.updatedAt = Date.now();
+        await store.save(data);
+      }
+    },
+    async updateStatus(sessionId, status) {
+      const data = await store.load(sessionId);
+      if (data) {
+        data.status = status;
+        data.updatedAt = Date.now();
+        await store.save(data);
+      }
     }
   };
+  return store;
 }
 
 // src/session/index.ts
-function createSession(options = {}) {
+async function createSession(options = {}) {
   const store = options.store;
   const now = Date.now();
+  let sessionId = options.id;
+  if (!sessionId && store?.generateSessionId) {
+    sessionId = await store.generateSessionId();
+  }
+  if (!sessionId) {
+    sessionId = generateId();
+  }
   const data = options._data ?? {
-    id: options.id ?? generateId(),
+    id: sessionId,
     agentId: options.agentId,
-    messages: [],
+    turns: [],
     runs: [],
+    status: "idle",
     metadata: options.metadata ?? {},
     createdAt: now,
     updatedAt: now
@@ -167,15 +284,18 @@ function createSession(options = {}) {
   function findRun(runId) {
     return data.runs.find((r) => r.id === runId);
   }
-  return {
+  const session = {
     get id() {
       return data.id;
     },
     get agentId() {
       return data.agentId;
     },
-    get messages() {
-      return data.messages;
+    get turns() {
+      return data.turns;
+    },
+    get status() {
+      return data.status;
     },
     get runs() {
       return data.runs;
@@ -232,14 +352,35 @@ function createSession(options = {}) {
       }
       touch();
     },
-    pushMessages(messages) {
-      data.messages.push(...messages);
+    async appendTurns(turns) {
+      data.turns.push(...turns);
       touch();
+      if (store) {
+        await store.appendTurns(data.id, turns);
+      }
     },
-    setMessages(messages) {
-      data.messages = messages;
+    setTurns(turns) {
+      data.turns = turns;
       touch();
     },
+    async updateStatus(status) {
+      data.status = status;
+      touch();
+      if (store) {
+        await store.updateStatus(data.id, status);
+      }
+    },
+    async updateRun(run) {
+      if (store) {
+        await store.updateRun(data.id, run);
+      }
+    },
+    generateTurnId() {
+      if (store?.generateTurnId) {
+        return store.generateTurnId();
+      }
+      return crypto.randomUUID();
+    },
     setMeta(key, value) {
       data.metadata[key] = value;
       touch();
@@ -254,6 +395,7 @@ function createSession(options = {}) {
       return JSON.parse(JSON.stringify(data));
     }
   };
+  return session;
 }
 async function loadSession(store, sessionId) {
   const loaded = await store.load(sessionId);

package/dist/{chunk-34KXKPNN.js → chunk-N523NBO2.js}

@@ -5,7 +5,7 @@ import {
   shell,
   spawn_exports,
   writeFile
-} from "./chunk-27EP7HB3.js";
+} from "./chunk-SWS5624X.js";
 import {
   __toCommonJS
 } from "./chunk-PNKVD2UK.js";

package/dist/{chunk-27EP7HB3.js → chunk-SWS5624X.js}

@@ -287,6 +287,9 @@ var init_validation = __esm({
 });
 
 // src/loop.ts
+function turnsToMessages(turns) {
+  return turns.map((t) => ({ role: t.role, content: t.content }));
+}
 async function runLoop(ctx) {
   let totalIn = 0;
   let totalOut = 0;
@@ -309,14 +312,26 @@ async function runLoop(ctx) {
     if (ctx.steeringQueue.length > 0) {
       const steerMsg = ctx.steeringQueue.shift();
       await ctx.hooks.callHook("steer:inject", { message: steerMsg });
-      ctx.messages.push(ctx.provider.userMessage(steerMsg));
+      const steerUserMsg = ctx.provider.userMessage(steerMsg);
+      ctx.turns.push({
+        id: await ctx.generateTurnId(),
+        role: steerUserMsg.role,
+        content: steerUserMsg.content,
+        createdAt: Date.now()
+      });
       continue;
     }
     if (result.ended) {
       if (ctx.followUpQueue.length > 0) {
         const followUp = ctx.followUpQueue.shift();
         await ctx.hooks.callHook("steer:inject", { message: followUp });
-        ctx.messages.push(ctx.provider.userMessage(followUp));
+        const followUpMsg = ctx.provider.userMessage(followUp);
+        ctx.turns.push({
+          id: await ctx.generateTurnId(),
+          role: followUpMsg.role,
+          content: followUpMsg.content,
+          createdAt: Date.now()
+        });
         continue;
       }
       return { totalIn, totalOut, turns: turn + 1, elapsed: Date.now() - startTime, turnUsage: turnUsages };
@@ -327,37 +342,59 @@ async function runLoop(ctx) {
   return stats;
 }
 async function executeTurn(ctx, turn) {
+  const turnId = await ctx.generateTurnId();
+  const messages = turnsToMessages(ctx.turns);
   const streamOptions = {
     model: ctx.model,
     system: ctx.system,
     tools: ctx.formattedTools,
-    messages: ctx.messages,
+    messages,
     maxTokens: 16384,
     thinking: ctx.thinking,
     signal: ctx.signal
   };
-  await ctx.hooks.callHook("context:transform", { messages: ctx.messages });
-  await ctx.hooks.callHook("turn:before", { turn, options: streamOptions });
+  await ctx.hooks.callHook("context:transform", { messages });
+  await ctx.hooks.callHook("turn:before", { turn, turnId, options: streamOptions });
   let currentText = "";
+  const blockIndex = 0;
   const result = await ctx.provider.stream(
     streamOptions,
     {
       onText(delta) {
         currentText += delta;
-        ctx.hooks.callHook("stream:text", { delta, text: currentText });
+        ctx.hooks.callHook("stream:text", { delta, text: currentText, turnId, blockIndex });
       }
     }
   );
   if (currentText) {
-    await ctx.hooks.callHook("stream:end", { text: currentText });
+    await ctx.hooks.callHook("stream:end", { text: currentText, turnId, blockIndex });
   }
-  await ctx.hooks.callHook("turn:after", { turn, usage: result.usage });
+  await ctx.hooks.callHook("turn:after", { turn, turnId, usage: result.usage });
   if (result.done) {
+    ctx.turns.push({
+      id: turnId,
+      role: "assistant",
+      content: result.assistantMessage?.content ?? [{ type: "text", text: currentText }],
+      usage: result.usage,
+      createdAt: Date.now()
+    });
     return { ended: true, usage: result.usage };
   }
-  ctx.messages.push(result.assistantMessage);
+  ctx.turns.push({
+    id: turnId,
+    role: "assistant",
+    content: result.assistantMessage.content,
+    usage: result.usage,
+    createdAt: Date.now()
+  });
   const toolResults = ctx.toolExecution === "parallel" ? await executeToolsParallel(ctx, result.toolCalls) : await executeToolsSequential(ctx, result.toolCalls);
-  ctx.messages.push(ctx.provider.toolResultsMessage(toolResults));
+  const toolResultMsg = ctx.provider.toolResultsMessage(toolResults);
+  ctx.turns.push({
+    id: await ctx.generateTurnId(),
+    role: toolResultMsg.role,
+    content: toolResultMsg.content,
+    createdAt: Date.now()
+  });
   return { ended: false, usage: result.usage };
 }
 async function executeSingleTool(ctx, call) {
@@ -412,8 +449,20 @@ async function executeToolsSequential(ctx, toolCalls) {
       for (const skipped of toolCalls.slice(toolCalls.indexOf(call))) {
         results.push({ id: skipped.id, content: "Skipped: steering message received" });
       }
-      ctx.messages.push(ctx.provider.toolResultsMessage(results));
-      ctx.messages.push(ctx.provider.userMessage(steerMsg));
+      const toolResultMsg = ctx.provider.toolResultsMessage(results);
+      ctx.turns.push({
+        id: await ctx.generateTurnId(),
+        role: toolResultMsg.role,
+        content: toolResultMsg.content,
+        createdAt: Date.now()
+      });
+      const steerUserMsg = ctx.provider.userMessage(steerMsg);
+      ctx.turns.push({
+        id: await ctx.generateTurnId(),
+        role: steerUserMsg.role,
+        content: steerUserMsg.content,
+        createdAt: Date.now()
+      });
       return [];
     }
     const { result } = await executeSingleTool(ctx, call);
@@ -447,8 +496,8 @@ function createAgent({ harness, provider, toolExecution = "sequential", executio
   const allMcpServers = [...harness.mcpServers ?? [], ...mcpServers ?? []];
   const steeringQueue = [];
   const followUpQueue = [];
-  let conversationMessages = session?.messages ?? [];
-  let runCounter = 0;
+  let conversationTurns = session?.turns.slice() ?? [];
+  let runCounter = session?.runs.length ?? 0;
   async function run(options) {
     if (running) {
       throw new Error("Agent is already running. Use steer() or followUp() to queue messages, or waitForIdle().");
@@ -457,8 +506,10 @@ function createAgent({ harness, provider, toolExecution = "sequential", executio
     abortController = new AbortController();
     const runId = `run_${++runCounter}`;
     session?.startRun(runId, options.prompt);
-    if (session)
+    if (session) {
+      await session.updateStatus("running");
       await hooks.callHook("session:start", { sessionId: session.id, runId, prompt: options.prompt });
+    }
     if (options.signal) {
       if (options.signal.aborted) {
         abortController.abort();
@@ -496,18 +547,44 @@ function createAgent({ harness, provider, toolExecution = "sequential", executio
       })
     );
     const formattedTools = provider.formatTools(toolSpecs);
-    const messages = [];
+    const turns = [];
+    const isResume = session && session.turns.length > 0 && session.runs.length > 0;
+    if (isResume) {
+      turns.push(...session.turns);
+    }
     if (options.system) {
       await hooks.callHook("system:before", { system: options.system });
-      messages.push(provider.userMessage(options.system));
-      messages.push(provider.assistantMessage("Understood. I will proceed with these instructions above the rest of my system prompt."));
+      const systemUserMsg = provider.userMessage(options.system);
+      turns.push({
+        id: crypto.randomUUID(),
+        role: systemUserMsg.role,
+        content: systemUserMsg.content,
+        createdAt: Date.now()
+      });
+      const systemAckMsg = provider.assistantMessage("Understood. I will proceed with these instructions above the rest of my system prompt.");
+      turns.push({
+        id: crypto.randomUUID(),
+        role: systemAckMsg.role,
+        content: systemAckMsg.content,
+        createdAt: Date.now()
+      });
     }
-    messages.push(provider.userMessage(options.prompt, options.images));
-    conversationMessages = messages;
-    session?.setMessages(messages);
-    const unregisterSessionSync = session ? hooks.hook("turn:after", () => {
-      session.setMessages(messages);
-      hooks.callHook("session:messages", { sessionId: session.id, count: messages.length });
+    const promptMsg = provider.userMessage(options.prompt, options.images);
+    turns.push({
+      id: crypto.randomUUID(),
+      role: promptMsg.role,
+      content: promptMsg.content,
+      createdAt: Date.now()
+    });
+    conversationTurns = turns;
+    let lastPersistedTurnCount = isResume ? session.turns.length : 0;
+    const unregisterSessionSync = session ? hooks.hook("turn:after", async () => {
+      const newTurns = turns.slice(lastPersistedTurnCount);
+      if (newTurns.length > 0) {
+        await session.appendTurns(newTurns);
+        lastPersistedTurnCount = turns.length;
+        hooks.callHook("session:turns", { sessionId: session.id, count: turns.length });
+      }
     }) : void 0;
     try {
       const stats = await runLoop({
@@ -526,7 +603,8 @@ function createAgent({ harness, provider, toolExecution = "sequential", executio
         handle: executionHandle,
         steeringQueue,
         followUpQueue,
-        messages
+        turns,
+        generateTurnId: () => session?.generateTurnId() ?? crypto.randomUUID()
       });
       const finalStats = {
         ...stats,
@@ -534,15 +612,24 @@ function createAgent({ harness, provider, toolExecution = "sequential", executio
       };
       if (abortController.signal.aborted) {
         session?.abortRun(runId);
-        if (session)
+        if (session) {
+          const run2 = session.runs.find((r) => r.id === runId);
+          if (run2)
+            await session.updateRun(run2);
+          await session.updateStatus("idle");
           await hooks.callHook("session:end", { sessionId: session.id, runId, status: "aborted" });
+        }
         await hooks.callHook("agent:done", finalStats);
         return finalStats;
       }
       const totalCost = finalStats.turnUsage?.reduce((sum, t) => sum + (t.cost ?? 0), 0) || void 0;
       if (totalCost)
         finalStats.cost = totalCost;
-      session?.setMessages(messages);
+      const finalNewTurns = turns.slice(lastPersistedTurnCount);
+      if (session && finalNewTurns.length > 0) {
+        await session.appendTurns(finalNewTurns);
+        lastPersistedTurnCount = turns.length;
+      }
       session?.completeRun(runId, {
         turns: finalStats.turns,
         tokensIn: finalStats.totalIn,
@@ -550,22 +637,37 @@ function createAgent({ harness, provider, toolExecution = "sequential", executio
         turnUsage: finalStats.turnUsage,
         cost: totalCost
       });
-      if (session)
+      if (session) {
+        const run2 = session.runs.find((r) => r.id === runId);
+        if (run2)
+          await session.updateRun(run2);
+        await session.updateStatus("completed");
         await hooks.callHook("session:end", { sessionId: session.id, runId, status: "completed" });
+      }
       await hooks.callHook("agent:done", finalStats);
       return finalStats;
     } catch (err) {
       if (abortController.signal.aborted) {
         session?.abortRun(runId);
-        if (session)
+        if (session) {
+          const run2 = session.runs.find((r) => r.id === runId);
+          if (run2)
+            await session.updateRun(run2);
+          await session.updateStatus("idle");
           await hooks.callHook("session:end", { sessionId: session.id, runId, status: "aborted" });
+        }
         const stats = { totalIn: 0, totalOut: 0, turns: 0, elapsed: 0 };
         await hooks.callHook("agent:done", stats);
         return stats;
       }
       session?.errorRun(runId, err.message);
-      if (session)
+      if (session) {
+        const run2 = session.runs.find((r) => r.id === runId);
+        if (run2)
+          await session.updateRun(run2);
+        await session.updateStatus("error");
         await hooks.callHook("session:end", { sessionId: session.id, runId, status: "error" });
+      }
       throw err;
     } finally {
       unregisterSpawnHook();
@@ -592,7 +694,7 @@ function createAgent({ harness, provider, toolExecution = "sequential", executio
     return idlePromise ?? Promise.resolve();
   }
   function reset() {
-    conversationMessages = [];
+    conversationTurns = [];
     steeringQueue.length = 0;
     followUpQueue.length = 0;
   }
@@ -630,8 +732,8 @@ function createAgent({ harness, provider, toolExecution = "sequential", executio
     get isRunning() {
       return running;
     },
-    get messages() {
-      return conversationMessages;
+    get turns() {
+      return conversationTurns;
     },
     get execution() {
       return executionContext;
@@ -731,7 +833,7 @@ function createSpawnTool(options = {}) {
           task,
           stats
         });
-        const response = extractText(agent.messages.at(-1));
+        const response = extractText(agent.turns.at(-1));
         return [
           `[sub-agent ${id}] Completed in ${stats.turns} turns (${stats.elapsed}ms)`,
           `Tokens: ${stats.totalIn} in / ${stats.totalOut} out`,
@@ -831,7 +933,7 @@ var init_spawn = __esm({
             task,
             stats
           });
-          const response = extractText(agent.messages.at(-1));
+          const response = extractText(agent.turns.at(-1));
           return [
             `[sub-agent ${id}] Completed in ${stats.turns} turns (${stats.elapsed}ms)`,
             `Tokens: ${stats.totalIn} in / ${stats.totalOut} out`,

package/dist/harnesses.d.ts

@@ -1,7 +1,7 @@
 import '@anthropic-ai/sdk';
 import 'hookable';
-export { H as Harness, f as HarnessConfig, T as ToolContext, g as ToolDef, h as ToolMap, _ as basic, l as basicTools, k as defineHarness } from './agent-DvZm8U14.js';
+export { H as Harness, f as HarnessConfig, T as ToolContext, g as ToolDef, h as ToolMap, _ as basic, l as basicTools, k as defineHarness } from './agent-DxIUxou4.js';
 import './providers.js';
-import './types-4CFQ-6Qu.js';
+import './types-CLRMCak3.js';
 import '@modelcontextprotocol/sdk/client/index.js';
 import './session.js';

package/dist/harnesses.js

@@ -2,8 +2,8 @@ import {
   basicTools,
   basic_default,
   defineHarness
-} from "./chunk-34KXKPNN.js";
-import "./chunk-27EP7HB3.js";
+} from "./chunk-N523NBO2.js";
+import "./chunk-SWS5624X.js";
 import "./chunk-26LIQARN.js";
 import "./chunk-PNKVD2UK.js";
 export {

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { S as SpawnConfig, E as ExecutionContext, a as ExecResult } from './agent-DvZm8U14.js';
-export { A as Agent, b as AgentHooks, c as AgentOptions, C as ContextCapabilities, d as ContextType, e as ExecutionHandle, H as Harness, f as HarnessConfig, M as McpConnection, T as ToolContext, g as ToolDef, h as ToolMap, i as connectMcpServers, j as createAgent, k as defineHarness } from './agent-DvZm8U14.js';
+import { S as SpawnConfig, E as ExecutionContext, a as ExecResult } from './agent-DxIUxou4.js';
+export { A as Agent, b as AgentHooks, c as AgentOptions, C as ContextCapabilities, d as ContextType, e as ExecutionHandle, H as Harness, f as HarnessConfig, M as McpConnection, T as ToolContext, g as ToolDef, h as ToolMap, i as connectMcpServers, j as createAgent, k as defineHarness } from './agent-DxIUxou4.js';
 export { CreateSessionOptions, RemoteStoreOptions, Session, SessionData, SessionRun, SessionStore, SqliteStoreOptions, autoDetectAndConvert, createMemoryStore, createRemoteStore, createSession, createSqliteStore, fromAnthropic, fromOpenAI, loadSession, toAnthropic, toOpenAI } from './session.js';
-export { C as ChildAgent, S as SpawnToolOptions, a as SpawnToolState, c as createSpawnTool, s as spawn } from './spawn-pP2grsVp.js';
-export { A as AgentRunOptions, a as AgentStats, I as ImageContent, M as McpServerConfig, S as SessionContentBlock, b as SessionMessage, T as ThinkingLevel, c as ToolExecutionMode, d as TurnUsage } from './types-4CFQ-6Qu.js';
+export { C as ChildAgent, S as SpawnToolOptions, a as SpawnToolState, c as createSpawnTool, s as spawn } from './spawn-bEqlGUVT.js';
+export { A as AgentRunOptions, a as AgentStats, I as ImageContent, M as McpServerConfig, S as SessionContentBlock, b as SessionMessage, c as SessionTurn, T as ThinkingLevel, d as ToolExecutionMode, e as TurnUsage } from './types-CLRMCak3.js';
 import 'hookable';
 import '@anthropic-ai/sdk';
 import '@modelcontextprotocol/sdk/client/index.js';

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   defineHarness
-} from "./chunk-34KXKPNN.js";
+} from "./chunk-N523NBO2.js";
 import {
   createAgent,
   createDockerContext,
@@ -10,7 +10,7 @@ import {
   init_agent,
   init_contexts,
   spawn
-} from "./chunk-27EP7HB3.js";
+} from "./chunk-SWS5624X.js";
 import {
   connectMcpServers,
   init_mcp
@@ -21,7 +21,7 @@ import {
   createSession,
   createSqliteStore,
   loadSession
-} from "./chunk-LMSOIIAT.js";
+} from "./chunk-IC2WAUBZ.js";
 import {
   autoDetectAndConvert,
   fromAnthropic,

package/dist/mcp.d.ts

@@ -1,6 +1,6 @@
 import 'hookable';
-export { M as McpConnection, i as connectMcpServers, r as resultToString } from './agent-DvZm8U14.js';
-export { M as McpServerConfig } from './types-4CFQ-6Qu.js';
+export { M as McpConnection, i as connectMcpServers, r as resultToString } from './agent-DxIUxou4.js';
+export { M as McpServerConfig } from './types-CLRMCak3.js';
 import '@modelcontextprotocol/sdk/client/index.js';
 import '@anthropic-ai/sdk';
 import './providers.js';

package/dist/providers.d.ts

@@ -1,4 +1,4 @@
-import { b as SessionMessage, T as ThinkingLevel, I as ImageContent, d as TurnUsage } from './types-4CFQ-6Qu.js';
+import { b as SessionMessage, T as ThinkingLevel, I as ImageContent, e as TurnUsage } from './types-CLRMCak3.js';
 
 declare function anthropic(): Provider;
 

package/dist/session.d.ts

@@ -1,5 +1,5 @@
-import { b as SessionMessage, d as TurnUsage } from './types-4CFQ-6Qu.js';
-export { S as SessionContentBlock } from './types-4CFQ-6Qu.js';
+import { b as SessionMessage, c as SessionTurn, e as TurnUsage } from './types-CLRMCak3.js';
+export { S as SessionContentBlock } from './types-CLRMCak3.js';
 
 /**
  * In-memory session store.
@@ -37,10 +37,14 @@ declare function autoDetectAndConvert(msg: {
  * Remote session store via HTTP API.
  *
  * Expects a REST API with:
- *   GET    {url}/sessions/{id}          -> SessionData | 404
- *   PUT    {url}/sessions/{id}          -> save SessionData
- *   DELETE {url}/sessions/{id}          -> delete
- *   GET    {url}/sessions?agentId=&limit= -> { ids: string[] }
+ *   GET    {url}/sessions/{id}                    -> SessionData | 404
+ *   PUT    {url}/sessions/{id}                    -> save SessionData
+ *   DELETE {url}/sessions/{id}                    -> delete
+ *   GET    {url}/sessions?agentId=&limit=         -> { ids: string[] }
+ *   POST   {url}/sessions/{id}/turns              -> append turns
+ *   GET    {url}/sessions/{id}/turns?from=&limit= -> SessionTurn[]
+ *   PUT    {url}/sessions/{id}/runs/{runId}        -> update run
+ *   PATCH  {url}/sessions/{id}                    -> { status }
  */
 
 interface RemoteStoreOptions {
@@ -64,7 +68,7 @@ declare function createSqliteStore(options: SqliteStoreOptions): SessionStore;
 /**
  * Session management for agents.
  *
- * A session tracks identity, message history, and run metadata.
+ * A session tracks identity, turn history, and run metadata.
  * Plug in any storage backend by implementing the SessionStore interface,
  * or use one of the built-in stores: memory, sqlite, remote.
  */
@@ -89,32 +93,47 @@ interface SessionRun {
 interface SessionData {
     id: string;
     agentId?: string;
-    messages: SessionMessage[];
+    turns: SessionTurn[];
     runs: SessionRun[];
+    status: 'idle' | 'running' | 'completed' | 'error';
     metadata: Record<string, unknown>;
     createdAt: number;
     updatedAt: number;
 }
 interface SessionStore {
+    /** Optional: generate a session ID server-side (e.g. Supabase UUID). */
+    generateSessionId?: () => string | Promise<string>;
+    /** Optional: generate a turn ID server-side. */
+    generateTurnId?: () => string | Promise<string>;
     /** Load a session by ID. Returns null if not found. */
     load: (sessionId: string) => Promise<SessionData | null>;
-    /** Save a session (create or update). */
+    /** Save a session (create or update, full document). */
     save: (session: SessionData) => Promise<void>;
     /** Delete a session. */
     delete: (sessionId: string) => Promise<void>;
-    /** List session IDs, optionally filtered by agentId. */
+    /** List session IDs, optionally filtered. */
     list: (filter?: {
         agentId?: string;
         limit?: number;
     }) => Promise<string[]>;
+    /** Append new turns to a session (incremental, avoids full re-save). */
+    appendTurns: (sessionId: string, turns: SessionTurn[]) => Promise<void>;
+    /** Return a slice of turns for a session. */
+    getTurns: (sessionId: string, from?: number, limit?: number) => Promise<SessionTurn[]>;
+    /** Persist an updated run record (called after completeRun / abortRun / errorRun). */
+    updateRun: (sessionId: string, run: SessionRun) => Promise<void>;
+    /** Update the top-level status of a session. */
+    updateStatus: (sessionId: string, status: SessionData['status']) => Promise<void>;
 }
 interface Session {
     /** Session ID */
     readonly id: string;
     /** Agent ID (optional label) */
     readonly agentId?: string;
-    /** Current message history */
-    readonly messages: SessionMessage[];
+    /** Current turn history */
+    readonly turns: SessionTurn[];
+    /** Top-level session status */
+    readonly status: SessionData['status'];
     /** All runs in this session */
     readonly runs: SessionRun[];
     /** Arbitrary metadata */
@@ -133,19 +152,25 @@ interface Session {
     abortRun: (runId: string) => void;
     /** Mark a run as errored */
     errorRun: (runId: string, error: string) => void;
-    /** Append messages to the session history */
-    pushMessages: (messages: SessionMessage[]) => void;
-    /** Replace all messages (e.g. after context:transform) */
-    setMessages: (messages: SessionMessage[]) => void;
+    /** Append turns to in-memory history AND persist via store.appendTurns (if store present) */
+    appendTurns: (turns: SessionTurn[]) => Promise<void>;
+    /** Replace all turns in-memory (does not persist — use save() for that) */
+    setTurns: (turns: SessionTurn[]) => void;
+    /** Update the session status in memory AND via store.updateStatus (if store present) */
+    updateStatus: (status: SessionData['status']) => Promise<void>;
+    /** Persist an updated run record via store.updateRun (if store present) */
+    updateRun: (run: SessionRun) => Promise<void>;
+    /** Generate a turn ID using store.generateTurnId if available, else crypto.randomUUID() */
+    generateTurnId: () => string | Promise<string>;
     /** Set metadata key */
     setMeta: (key: string, value: unknown) => void;
-    /** Persist the session to the store */
+    /** Persist the full session document to the store */
     save: () => Promise<void>;
     /** Serialize to SessionData */
     toJSON: () => SessionData;
 }
 interface CreateSessionOptions {
-    /** Session ID (auto-generated if not provided) */
+    /** Session ID. If omitted and store provides generateSessionId, that is used. */
     id?: string;
     /** Agent ID label */
     agentId?: string;
@@ -157,11 +182,12 @@ interface CreateSessionOptions {
 }
 /**
  * Create a new session.
+ * Async so stores that generate IDs server-side (e.g. Supabase) can be supported.
  */
-declare function createSession(options?: CreateSessionOptions): Session;
+declare function createSession(options?: CreateSessionOptions): Promise<Session>;
 /**
  * Load an existing session from a store.
  */
 declare function loadSession(store: SessionStore, sessionId: string): Promise<Session | null>;
 
-export { type CreateSessionOptions, type RemoteStoreOptions, type Session, type SessionData, SessionMessage, type SessionRun, type SessionStore, type SqliteStoreOptions, autoDetectAndConvert, createMemoryStore, createRemoteStore, createSession, createSqliteStore, fromAnthropic, fromOpenAI, loadSession, toAnthropic, toOpenAI };
+export { type CreateSessionOptions, type RemoteStoreOptions, type Session, type SessionData, SessionMessage, type SessionRun, type SessionStore, SessionTurn, type SqliteStoreOptions, autoDetectAndConvert, createMemoryStore, createRemoteStore, createSession, createSqliteStore, fromAnthropic, fromOpenAI, loadSession, toAnthropic, toOpenAI };

package/dist/session.js

@@ -4,7 +4,7 @@ import {
   createSession,
   createSqliteStore,
   loadSession
-} from "./chunk-LMSOIIAT.js";
+} from "./chunk-IC2WAUBZ.js";
 import {
   autoDetectAndConvert,
   fromAnthropic,

package/dist/{spawn-pP2grsVp.d.ts → spawn-bEqlGUVT.d.ts}

@@ -1,5 +1,5 @@
-import { f as HarnessConfig, g as ToolDef } from './agent-DvZm8U14.js';
-import { a as AgentStats } from './types-4CFQ-6Qu.js';
+import { f as HarnessConfig, g as ToolDef } from './agent-DxIUxou4.js';
+import { a as AgentStats } from './types-CLRMCak3.js';
 
 /**
  * Spawn tool — create sub-agents from a parent agent.

package/dist/tools.d.ts

@@ -1,8 +1,8 @@
-import { g as ToolDef } from './agent-DvZm8U14.js';
-export { C as ChildAgent, S as SpawnToolOptions, a as SpawnToolState, c as createSpawnTool, s as spawn } from './spawn-pP2grsVp.js';
+import { g as ToolDef } from './agent-DxIUxou4.js';
+export { C as ChildAgent, S as SpawnToolOptions, a as SpawnToolState, c as createSpawnTool, s as spawn } from './spawn-bEqlGUVT.js';
 import 'hookable';
 import '@anthropic-ai/sdk';
-import './types-4CFQ-6Qu.js';
+import './types-CLRMCak3.js';
 import '@modelcontextprotocol/sdk/client/index.js';
 import './providers.js';
 import './session.js';

package/dist/tools.js

@@ -6,7 +6,7 @@ import {
   spawn,
   validateToolArgs,
   writeFile
-} from "./chunk-27EP7HB3.js";
+} from "./chunk-SWS5624X.js";
 import "./chunk-26LIQARN.js";
 import "./chunk-PNKVD2UK.js";
 export {

package/dist/{types-4CFQ-6Qu.d.ts → types-CLRMCak3.d.ts}

@@ -52,6 +52,16 @@ interface SessionMessage {
     role: 'user' | 'assistant';
     content: SessionContentBlock[];
 }
+interface SessionTurn {
+    /** UUID — generated by the store if it provides generateTurnId, else crypto.randomUUID() */
+    id: string;
+    role: 'user' | 'assistant' | 'system';
+    content: SessionContentBlock[];
+    /** Token usage — only present on assistant turns */
+    usage?: TurnUsage;
+    /** Unix timestamp (Date.now()) when the turn was created */
+    createdAt: number;
+}
 interface AgentRunOptions {
     model?: string;
     prompt: string;
@@ -91,4 +101,4 @@ interface ChildRunStats {
     stats: AgentStats;
 }
 
-export type { AgentRunOptions as A, ChildRunStats as C, ImageContent as I, McpServerConfig as M, SessionContentBlock as S, ThinkingLevel as T, AgentStats as a, SessionMessage as b, ToolExecutionMode as c, TurnUsage as d };
+export type { AgentRunOptions as A, ChildRunStats as C, ImageContent as I, McpServerConfig as M, SessionContentBlock as S, ThinkingLevel as T, AgentStats as a, SessionMessage as b, SessionTurn as c, ToolExecutionMode as d, TurnUsage as e };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zidane",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "an agent that goes straight to the goal",
   "type": "module",
   "private": false,