zidane 1.2.0 → 1.4.0

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-B4wguzkU.d.ts}

@@ -1,87 +1,11 @@
 import { Hookable } from 'hookable';
+import { E as ExecutionContext, c as ExecutionHandle, f as SkillsConfig, d as SkillConfig } from './types-D8fzooXc.js';
 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';
 
-/**
- * Execution context types.
- *
- * An execution context defines *where* and *how* an agent's tools run.
- * The agent loop and tools interact through this interface without knowing
- * whether they're running in-process, in a Docker container, or in a
- * remote sandbox.
- */
-interface ContextCapabilities {
-    /** Can execute shell commands */
-    shell: boolean;
-    /** Can read/write files in a workspace */
-    filesystem: boolean;
-    /** Can make outbound network requests */
-    network: boolean;
-    /** Has GPU access */
-    gpu: boolean;
-}
-/** Opaque handle to a running execution context instance */
-interface ExecutionHandle {
-    id: string;
-    type: ContextType;
-    /** Working directory within the context */
-    cwd: string;
-}
-interface ExecResult {
-    stdout: string;
-    stderr: string;
-    exitCode: number;
-}
-interface SpawnConfig {
-    /** Working directory (created if it doesn't exist) */
-    cwd?: string;
-    /** Environment variables */
-    env?: Record<string, string>;
-    /** Docker image (only for 'docker' context) */
-    image?: string;
-    /** Resource limits */
-    limits?: {
-        /** Memory limit in MB */
-        memory?: number;
-        /** CPU limit (e.g. '1.0' = 1 core) */
-        cpu?: string;
-        /** Timeout in seconds for the entire context lifetime */
-        timeout?: number;
-    };
-    /** Sandbox provider config (only for 'sandbox' context) */
-    sandbox?: {
-        provider: string;
-        apiKey?: string;
-        [key: string]: unknown;
-    };
-}
-type ContextType = 'process' | 'docker' | 'sandbox';
-interface ExecutionContext {
-    /** Context type identifier */
-    readonly type: ContextType;
-    /** What this context supports */
-    readonly capabilities: ContextCapabilities;
-    /** Spawn a new execution environment */
-    spawn: (config?: SpawnConfig) => Promise<ExecutionHandle>;
-    /** Execute a shell command in the context */
-    exec: (handle: ExecutionHandle, command: string, options?: {
-        cwd?: string;
-        env?: Record<string, string>;
-        timeout?: number;
-    }) => Promise<ExecResult>;
-    /** Read a file from the context's filesystem */
-    readFile: (handle: ExecutionHandle, path: string) => Promise<string>;
-    /** Write a file to the context's filesystem */
-    writeFile: (handle: ExecutionHandle, path: string, content: string) => Promise<void>;
-    /** List files in a directory */
-    listFiles: (handle: ExecutionHandle, path: string) => Promise<string[]>;
-    /** Destroy the execution environment and clean up resources */
-    destroy: (handle: ExecutionHandle) => Promise<void>;
-}
-
 /** Core tools available in every basic harness (without spawn) */
 declare const basicTools: {
     shell: ToolDef;
@@ -123,12 +47,19 @@ interface HarnessConfig {
     tools: Record<string, ToolDef>;
     /** MCP servers to connect and expose as tools */
     mcpServers?: McpServerConfig[];
+    /** Skills configuration at the harness level */
+    skills?: SkillsConfig;
 }
 /**
  * Define a harness with a name, optional system prompt, and tools.
  */
 declare function defineHarness(config: HarnessConfig): HarnessConfig;
 type Harness = HarnessConfig;
+/**
+ * A harness with no tools — for pure chat mode.
+ * Use with `enableTools: false` or when no tool access is needed.
+ */
+declare const noTools: HarnessConfig;
 
 /**
  * MCP (Model Context Protocol) server support.
@@ -168,18 +99,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;
@@ -252,6 +189,16 @@ interface AgentHooks {
         input: Record<string, unknown>;
         error: Error;
     }) => void;
+    'skills:resolve': (ctx: {
+        skills: SkillConfig[];
+    }) => void;
+    'skills:catalog': (ctx: {
+        catalog: string;
+        skills: SkillConfig[];
+    }) => void;
+    'skills:activate': (ctx: {
+        skill: SkillConfig;
+    }) => void;
     'agent:abort': (ctx: object) => void;
     'agent:done': (ctx: AgentStats) => void;
     'session:start': (ctx: {
@@ -264,7 +211,7 @@ interface AgentHooks {
         runId: string;
         status: 'completed' | 'aborted' | 'error';
     }) => void;
-    'session:messages': (ctx: {
+    'session:turns': (ctx: {
         sessionId: string;
         count: number;
     }) => void;
@@ -278,16 +225,21 @@ interface AgentHooks {
     }) => void;
 }
 interface AgentOptions {
-    harness: HarnessConfig;
+    /** Harness (tools + system prompt). Defaults to a no-tools harness if omitted. */
+    harness?: HarnessConfig;
     provider: Provider;
     /** Tool execution mode: 'sequential' (default) or 'parallel' */
     toolExecution?: ToolExecutionMode;
+    /** Enable tool use. When false, no tools are sent to the provider (pure chat mode). Default: true. */
+    enableTools?: boolean;
     /** Execution context: where tools run. Defaults to in-process. */
     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;
+    /** Skills configuration (merged with harness-level skills, agent takes precedence) */
+    skills?: SkillsConfig;
     /** @internal */
     _mcpConnector?: (configs: McpServerConfig[]) => Promise<McpConnection>;
 }
@@ -302,12 +254,12 @@ 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;
     meta: Record<string, unknown>;
 }
-declare function createAgent({ harness, provider, toolExecution, execution, mcpServers, session, _mcpConnector }: AgentOptions): Agent;
+declare function createAgent({ harness: harnessOption, provider, toolExecution, enableTools, execution, mcpServers, session, skills: agentSkills, _mcpConnector }: AgentOptions): Agent;
 
-export { type Agent as A, type ContextCapabilities as C, type ExecutionContext as E, type Harness as H, type McpConnection as M, type SpawnConfig as S, type ToolContext as T, _default as _, type ExecResult as a, type AgentHooks as b, type AgentOptions as c, type ContextType as d, type ExecutionHandle as e, type HarnessConfig as f, type ToolDef as g, type ToolMap as h, connectMcpServers as i, createAgent as j, defineHarness as k, basicTools as l, resultToString as r };
+export { type Agent as A, type Harness as H, type McpConnection as M, type ToolContext as T, _default as _, type AgentHooks as a, type AgentOptions as b, type HarnessConfig as c, type ToolDef as d, type ToolMap as e, connectMcpServers as f, createAgent as g, defineHarness as h, basicTools as i, noTools as n, resultToString as r };

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);