fix(docs/sdk): fix stale examples and add sessionId/autoSave to SessionOptions

Documentation fixes:
- README Quick Start TypeScript: defaultSecurity → securityProvider: new DefaultSecurityProvider()
- README Quick Start Python: fix constructor misuse and removed default_security field
- README Node.js/Python SDK sections: add typed class imports, show sessionId/autoSave persistence flow
- SUBAGENT_PERMISSIVE_MODE.md: add missing await on all Agent.create() calls (3 occurrences)

SDK additions (Node.js + Python):
- SessionOptions.sessionId / session_id: set a stable ID for save-and-resume workflows
- SessionOptions.autoSave / auto_save: persist session after each turn automatically
- Both fields wired through js_session_options_to_rust() and build_rust_session_options()

Example files updated to use current API:
- memoryDir/memory_dir → memoryStore: new FileMemoryStore(dir) / opts.memory_store = FileMemoryStore(dir)
- defaultSecurity/default_security → securityProvider: new DefaultSecurityProvider() / opts.security_provider = DefaultSecurityProvider()
- Imports updated in all four files

Author: RoyLin

README.md

@@ -85,11 +85,11 @@ async fn main() -> anyhow::Result<()> {
 <summary><b>TypeScript</b></summary>
 
 ```typescript
-import { Agent } from '@a3s-lab/code';
+import { Agent, DefaultSecurityProvider } from '@a3s-lab/code';
 
 const agent = await Agent.create('agent.hcl');
 const session = agent.session('.', {
-  defaultSecurity: true,
+  securityProvider: new DefaultSecurityProvider(),
   builtinSkills: true,
   planning: true,
 });
@@ -104,14 +104,13 @@ console.log(result.text);
 <summary><b>Python</b></summary>
 
 ```python
-from a3s_code import Agent, SessionOptions
+from a3s_code import Agent, SessionOptions, DefaultSecurityProvider
 
 agent = Agent("agent.hcl")
-session = agent.session(".", SessionOptions(
-    default_security=True,
-    builtin_skills=True,
-    planning=True,
-))
+opts = SessionOptions()
+opts.security_provider = DefaultSecurityProvider()
+opts.builtin_skills = True
+session = agent.session(".", opts, planning=True)
 
 result = session.send("Refactor auth + update tests")
 print(result.text)
@@ -135,6 +134,7 @@ print(result.text)
 | **Git** | `git_worktree` | Create/list/remove/status git worktrees for parallel work |
 | **Subagents** | `task` | Delegate to a named agent; blocks until the child agent replies |
 | **Parallel subagents** | `parallel_task` | Fan-out to multiple named agents concurrently |
+| **Team workflow** | `run_team` | Lead → Worker → Reviewer team with dynamic decomposition and quality review |
 | **Parallel tools** | `batch` | Execute multiple tools concurrently in one call |
 
 ---
@@ -556,6 +556,28 @@ for task in result.done_tasks:
 
 Supports Lead/Worker/Reviewer roles, `mpsc` peer messaging, broadcast, and a full task lifecycle (Open → InProgress → InReview → Done/Rejected).
 
+**`run_team` built-in tool** — The LLM can also trigger the same Lead → Worker → Reviewer workflow autonomously at runtime via the `run_team` tool (no SDK wiring required):
+
+```python
+# Python — call directly from SDK code
+result = session.tool("run_team", {
+    "goal": "Audit the auth module for security issues and produce a remediation plan",
+    "max_steps": 10,  # per-member agent; lead/worker/reviewer all default to "general"
+})
+print(result.output)
+```
+
+```typescript
+// TypeScript — call directly from SDK code
+const result = await session.tool('run_team', {
+  goal: 'Audit the auth module for security issues and produce a remediation plan',
+  maxSteps: 10,
+});
+console.log(result.output);
+```
+
+The LLM can also call `run_team` on its own when the `delegate-task` skill is loaded — it selects it automatically for goals with an unknown number of subtasks or that require reviewer sign-off.
+
 ---
 
 ### 🎛️ Agent Orchestrator (Master-SubAgent Coordination)
@@ -1064,7 +1086,7 @@ tasks = board.by_status("done")      # "open"|"in_progress"|"in_review"|"done"|"
 ### Python SDK
 
 ```python
-from a3s_code import Agent, SessionOptions, builtin_skills
+from a3s_code import Agent, SessionOptions, builtin_skills, DefaultSecurityProvider, FileMemoryStore, FileSessionStore, MemorySessionStore
 
 # Create agent
 agent = Agent("agent.hcl")
@@ -1108,9 +1130,13 @@ agent.refresh_mcp_tools()           # refresh global MCP tool cache
 stats = session.queue_stats()
 dead = session.dead_letters()
 
-# Persistence
-session.save()
-resumed = agent.resume_session(session.session_id, opts)
+# Persistence — set ID + auto-save, then resume later
+opts2 = SessionOptions()
+opts2.session_store = FileSessionStore('./sessions')
+opts2.session_id = 'my-session'
+opts2.auto_save = True
+session2 = agent.session(".", opts2)
+resumed = agent.resume_session('my-session', opts2)
 ```
 
 ### Node.js SDK — Agent Teams
@@ -1149,7 +1175,7 @@ const stats = board.stats();         // { open, inProgress, inReview, done, reje
 ### Node.js SDK
 
 ```typescript
-import { Agent } from '@a3s-lab/code';
+import { Agent, DefaultSecurityProvider, FileMemoryStore, FileSessionStore, MemorySessionStore } from '@a3s-lab/code';
 
 // Create agent
 const agent = await Agent.create('agent.hcl');
@@ -1194,9 +1220,13 @@ await agent.refreshMcpTools();             // refresh global MCP tool cache
 const stats = await session.queueStats();
 const dead = await session.deadLetters();
 
-// Persistence
-await session.save();
-const resumed = agent.resumeSession(session.sessionId, options);
+// Persistence — set ID + auto-save, then resume later
+const session2 = agent.session('.', {
+  sessionStore: new FileSessionStore('./sessions'),
+  sessionId: 'my-session',
+  autoSave: true,
+});
+const resumed = agent.resumeSession('my-session', { sessionStore: new FileSessionStore('./sessions') });
 ```
 
 ---

sdk/node/examples/SUBAGENT_PERMISSIVE_MODE.md

@@ -11,7 +11,7 @@ Version 1.0.3 introduces permissive mode support for sub-agents, allowing them t
 ```typescript
 import { Agent } from '@a3s-lab/code';
 
-const agent = Agent.create('~/.a3s/config.hcl');
+const agent = await Agent.create('~/.a3s/config.hcl');
 const session = agent.session('.', { permissive: true });
 
 // Spawn a sub-agent with permissive mode
@@ -32,7 +32,7 @@ console.log(result.output);
 const { Agent } = require('@a3s-lab/code');
 
 async function main() {
-  const agent = Agent.create('~/.a3s/config.hcl');
+  const agent = await Agent.create('~/.a3s/config.hcl');
   const session = agent.session('.', { permissive: true });
 
   // Spawn a sub-agent with permissive mode
@@ -55,7 +55,7 @@ main();
 ```typescript
 import { Agent } from '@a3s-lab/code';
 
-const agent = Agent.create('~/.a3s/config.hcl');
+const agent = await Agent.create('~/.a3s/config.hcl');
 const session = agent.session('.', { permissive: true });
 
 // Spawn multiple sub-agents in parallel
@@ -88,7 +88,7 @@ Monitor internal SubAgent events (tool calls, LLM responses):
 ```typescript
 import { Agent } from '@a3s-lab/code';
 
-const agent = Agent.create('~/.a3s/config.hcl');
+const agent = await Agent.create('~/.a3s/config.hcl');
 const session = agent.session('.', { permissive: true });
 
 // Stream events and monitor SubAgent activity

sdk/node/examples/advanced_features_demo.ts

@@ -24,6 +24,8 @@ import {
   AgentResult,
   ToolResult,
   builtinSkills,
+  FileMemoryStore,
+  DefaultSecurityProvider,
 } from '../index.js';
 import * as fs from 'fs';
 import * as path from 'path';
@@ -239,7 +241,7 @@ class AdvancedFeaturesDemo {
         'AWS_SECRET=AKIAIOSFODNN7EXAMPLE\n'
       );
 
-      const session: Session = this.agent.session(workspace, { defaultSecurity: true, permissive: true });
+      const session: Session = this.agent.session(workspace, { securityProvider: new DefaultSecurityProvider(), permissive: true });
 
       console.log('  Security: DefaultSecurityProvider enabled');
       console.log('  Features: taint tracking + output sanitization\n');
@@ -308,7 +310,7 @@ class AdvancedFeaturesDemo {
     const workspace: string = AdvancedFeaturesDemo.makeTempDir();
     const memoryDir: string = AdvancedFeaturesDemo.makeTempDir();
     try {
-      const session: Session = this.agent.session(workspace, { memoryDir, permissive: true });
+      const session: Session = this.agent.session(workspace, { memoryStore: new FileMemoryStore(memoryDir), permissive: true });
 
       console.log(`  Memory dir: ${memoryDir}\n`);
 

sdk/node/examples/test_advanced_features.ts

@@ -13,7 +13,7 @@
  * Requires a valid LLM API key in ~/.a3s/config.hcl or $A3S_CONFIG.
  */
 
-import { Agent, Session, AgentResult } from '../index.js';
+import { Agent, Session, AgentResult, FileMemoryStore, DefaultSecurityProvider } from '../index.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
@@ -68,7 +68,7 @@ class AdvancedFeaturesTest {
     const memDir: string = fs.mkdtempSync(path.join(os.tmpdir(), 'a3s-mem-'));
 
     const session: Session = agent.session(os.tmpdir(), {
-      memoryDir: memDir,
+      memoryStore: new FileMemoryStore(memDir),
     });
 
     const result: AgentResult = await session.send('Remember: my favorite language is Rust.');
@@ -88,7 +88,7 @@ class AdvancedFeaturesTest {
 
     // Enable default security: taint-tracks input, sanitizes output
     const session: Session = agent.session(os.tmpdir(), {
-      defaultSecurity: true,
+      securityProvider: new DefaultSecurityProvider(),
     });
 
     const result: AgentResult = await session.send('What is 2 + 2?');
@@ -181,10 +181,10 @@ class AdvancedFeaturesTest {
     const memDir: string = fs.mkdtempSync(path.join(os.tmpdir(), 'a3s-combined-'));
 
     const session: Session = agent.session(os.tmpdir(), {
-      defaultSecurity: true,
+      securityProvider: new DefaultSecurityProvider(),
       autoCompact: true,
       autoCompactThreshold: 0.9,
-      memoryDir: memDir,
+      memoryStore: new FileMemoryStore(memDir),
       permissive: true,
     });
 

sdk/node/index.d.ts

@@ -138,6 +138,19 @@ export interface SessionOptions {
   inlineSkills?: Array<InlineSkill>
   /** Override maximum number of tool-call rounds for this session. */
   maxToolRounds?: number
+  /**
+   * Session ID (auto-generated if not set).
+   *
+   * Set a stable ID so the session can be saved and resumed later:
+   * ```js
+   * agent.session('.', { sessionId: 'my-session', sessionStore: new FileSessionStore('./sessions'), autoSave: true });
+   * // Later:
+   * agent.resumeSession('my-session', { sessionStore: new FileSessionStore('./sessions') });
+   * ```
+   */
+  sessionId?: string
+  /** Automatically save the session to the configured store after each turn (default: false). */
+  autoSave?: boolean
 }
 /** A single message in conversation history. */
 export interface MessageObject {

sdk/node/src/lib.rs

@@ -794,6 +794,12 @@ fn js_session_options_to_rust(options: Option<SessionOptions>) -> RustSessionOpt
     if let Some(r) = o.max_tool_rounds {
         opts = opts.with_max_tool_rounds(r as usize);
     }
+    if let Some(id) = o.session_id {
+        opts = opts.with_session_id(id);
+    }
+    if o.auto_save.unwrap_or(false) {
+        opts = opts.with_auto_save(true);
+    }
     opts
 }
 

sdk/python/examples/advanced_features_demo.py

@@ -18,7 +18,7 @@
 import os
 import tempfile
 from pathlib import Path
-from a3s_code import Agent, SessionOptions, SessionQueueConfig, builtin_skills
+from a3s_code import Agent, SessionOptions, SessionQueueConfig, builtin_skills, DefaultSecurityProvider, FileMemoryStore
 
 
 class AdvancedFeaturesDemo:
@@ -200,7 +200,7 @@ def demo_security(self) -> None:
             )
 
             opts = SessionOptions()
-            opts.default_security = True
+            opts.security_provider = DefaultSecurityProvider()
             session = self.agent.session(workspace, options=opts, permissive=True)
 
             print("  Security: DefaultSecurityProvider enabled")
@@ -266,7 +266,7 @@ def demo_memory(self) -> None:
         with tempfile.TemporaryDirectory() as workspace:
             with tempfile.TemporaryDirectory() as memory_dir:
                 opts = SessionOptions()
-                opts.memory_dir = memory_dir
+                opts.memory_store = FileMemoryStore(memory_dir)
 
                 session = self.agent.session(workspace, options=opts, permissive=True)
 

sdk/python/examples/test_advanced_features.py

@@ -63,7 +63,7 @@ async def test_memory(self) -> None:
 
         try:
             opts = a3s_code.SessionOptions()
-            opts.memory_dir = mem_dir
+            opts.memory_store = a3s_code.FileMemoryStore(mem_dir)
 
             session = agent.session(tempfile.gettempdir(), options=opts)
             result = await session.send("Remember: my favorite language is Rust.")
@@ -80,7 +80,7 @@ async def test_security(self) -> None:
         agent = await a3s_code.Agent.create(self.config_path)
 
         opts = a3s_code.SessionOptions()
-        opts.default_security = True
+        opts.security_provider = a3s_code.DefaultSecurityProvider()
 
         session = agent.session(tempfile.gettempdir(), options=opts)
         result = await session.send("What is 2 + 2?")
@@ -164,10 +164,10 @@ async def test_combined(self) -> None:
 
         try:
             opts = a3s_code.SessionOptions()
-            opts.default_security = True
+            opts.security_provider = a3s_code.DefaultSecurityProvider()
             opts.auto_compact = True
             opts.auto_compact_threshold = 0.9
-            opts.memory_dir = mem_dir
+            opts.memory_store = a3s_code.FileMemoryStore(mem_dir)
 
             session = agent.session(tempfile.gettempdir(), options=opts, permissive=True)
 

sdk/python/src/lib.rs

@@ -1931,6 +1931,22 @@ struct PySessionOptions {
     inline_skills: Vec<(String, String, String)>,
     /// Override maximum number of tool-call rounds per session.
     max_tool_rounds: Option<usize>,
+    /// Session ID for this session (auto-generated if not set).
+    ///
+    /// Set a stable ID to save and resume the session later:
+    ///
+    /// .. code-block:: python
+    ///
+    ///     opts = SessionOptions()
+    ///     opts.session_store = FileSessionStore('./sessions')
+    ///     opts.session_id = 'my-session'
+    ///     opts.auto_save = True
+    ///     session = agent.session('.', opts)
+    ///     # Later:
+    ///     resumed = agent.resume_session('my-session', opts)
+    session_id: Option<String>,
+    /// Automatically save the session to the configured store after each turn (default: False).
+    auto_save: bool,
 }
 
 #[pymethods]
@@ -1954,6 +1970,8 @@ impl PySessionOptions {
             extra: None,
             inline_skills: vec![],
             max_tool_rounds: None,
+            session_id: None,
+            auto_save: false,
         }
     }
 
@@ -2143,6 +2161,28 @@ impl PySessionOptions {
         self.max_tool_rounds = value;
     }
 
+    /// Session ID (auto-generated if not set). Set to save and resume sessions by name.
+    #[getter]
+    fn get_session_id(&self) -> Option<String> {
+        self.session_id.clone()
+    }
+
+    #[setter]
+    fn set_session_id(&mut self, value: Option<String>) {
+        self.session_id = value;
+    }
+
+    /// Automatically save the session after each turn (default: False).
+    #[getter]
+    fn get_auto_save(&self) -> bool {
+        self.auto_save
+    }
+
+    #[setter]
+    fn set_auto_save(&mut self, value: bool) {
+        self.auto_save = value;
+    }
+
     /// Register an instruction skill programmatically.
     ///
     /// Instructions are injected into the system prompt at session start.
@@ -2489,6 +2529,12 @@ fn build_rust_session_options(so: PySessionOptions) -> RustSessionOptions {
     if let Some(r) = so.max_tool_rounds {
         o = o.with_max_tool_rounds(r);
     }
+    if let Some(id) = so.session_id {
+        o = o.with_session_id(id);
+    }
+    if so.auto_save {
+        o = o.with_auto_save(true);
+    }
     o
 }