feat(sdk): align Python and Node.js SessionOptions with Rust core

RoyLin · RoyLin · commit e204128434a0 · 2026-03-18T19:08:32.000+08:00
Add missing SessionOptions fields to both SDKs that were in the Rust core
but not exposed to language bindings:

**Both SDKs:**
- temperature (f32/number): sampling temperature, overrides provider default
- thinking_budget/thinkingBudget (usize/number): extended thinking token budget
- continuation_enabled/continuationEnabled (bool): enable/disable continuation injection
- max_continuation_turns/maxContinuationTurns (u32/number): max continuations per execution

**Python SDK only** (were kwargs-only, now also in SessionOptions object):
- planning: enable planning mode
- goal_tracking: enable goal tracking
- max_parse_retries: max consecutive parse errors before abort
- tool_timeout_ms: per-tool execution timeout
- circuit_breaker_threshold: max LLM API failures before abort

Integration tests in sdk/python/examples/test_api_alignment.py and
sdk/node/examples/test_api_alignment.ts verify all new fields against
kimi-k2.5 via KIMI_API_KEY + KIMI_BASE_URL environment variables.
diff --git a/sdk/node/examples/test_api_alignment.ts b/sdk/node/examples/test_api_alignment.ts
@@ -0,0 +1,211 @@
+/**
+ * Integration tests for Node.js SDK API alignment with Rust core.
+ *
+ * Tests the new SessionOptions fields added in this PR:
+ *   - temperature
+ *   - thinkingBudget
+ *   - continuationEnabled
+ *   - maxContinuationTurns
+ *
+ * Uses the kimi-k2.5 model. API key is read from KIMI_API_KEY environment
+ * variable.
+ *
+ * Usage:
+ *   KIMI_API_KEY=sk-... npx ts-node test_api_alignment.ts
+ */
+
+import { Agent, SessionOptions } from '@a3s-lab/code';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// HCL config that reads API key from KIMI_API_KEY env var (see agent_kimi_k2.5.hcl)
+const KIMI_HCL_CONFIG = path.join(__dirname, 'agent_kimi_k2.5.hcl');
+
+// ---------------------------------------------------------------------------
+// Test helpers
+// ---------------------------------------------------------------------------
+
+type Status = 'PASS' | 'FAIL' | 'SKIP';
+const results: Array<{ name: string; status: Status; detail: string }> = [];
+
+function check(name: string, condition: boolean, detail = '') {
+  const status: Status = condition ? 'PASS' : 'FAIL';
+  results.push({ name, status, detail });
+  const icon = condition ? '✓' : '✗';
+  const msg = detail ? `  ${icon} ${name}: ${detail}` : `  ${icon} ${name}`;
+  console.log(msg);
+  return condition;
+}
+
+function skip(name: string, reason: string) {
+  results.push({ name, status: 'SKIP', detail: reason });
+  console.log(`  - ${name}: SKIP (${reason})`);
+}
+
+function section(title: string) {
+  console.log(`\n${'='.repeat(60)}`);
+  console.log(`  ${title}`);
+  console.log('='.repeat(60));
+}
+
+// ---------------------------------------------------------------------------
+// Phase 1: SessionOptions type checks (no LLM call)
+// ---------------------------------------------------------------------------
+
+section('Phase 1: SessionOptions field type checks');
+
+// Verify new fields are accepted by TypeScript and accepted as undefined
+const opts: SessionOptions = {
+  temperature: undefined,
+  thinkingBudget: undefined,
+  continuationEnabled: undefined,
+  maxContinuationTurns: undefined,
+};
+check('temperature field accepted', true);
+check('thinkingBudget field accepted', true);
+check('continuationEnabled field accepted', true);
+check('maxContinuationTurns field accepted', true);
+
+const opts2: SessionOptions = {
+  temperature: 0.5,
+  thinkingBudget: 8000,
+  continuationEnabled: false,
+  maxContinuationTurns: 5,
+};
+check('temperature value 0.5', opts2.temperature === 0.5);
+check('thinkingBudget value 8000', opts2.thinkingBudget === 8000);
+check('continuationEnabled value false', opts2.continuationEnabled === false);
+check('maxContinuationTurns value 5', opts2.maxContinuationTurns === 5);
+
+// ---------------------------------------------------------------------------
+// Phase 2: Integration tests against kimi-k2.5
+// ---------------------------------------------------------------------------
+
+const apiKey = process.env.KIMI_API_KEY;
+
+async function runLiveTests(_apiKey: string) {
+  section('Phase 2: Live integration tests (kimi-k2.5)');
+
+  const cwd = process.cwd();
+
+  // --- 2a: basic send ---
+  console.log('\n  2a. Basic send');
+  try {
+    const agent = await Agent.create(KIMI_HCL_CONFIG);
+    const session = await agent.session(cwd);
+    const result = await session.send('Reply with exactly: HELLO');
+    check('basic send returns result', result != null);
+    check('basic send has text', Boolean(result?.text));
+    check('basic send contains HELLO', (result?.text ?? '').toUpperCase().includes('HELLO'),
+      `got: ${result?.text?.slice(0, 80)}`);
+  } catch (e: any) {
+    check('basic send', false, String(e));
+  }
+
+  // --- 2b: temperature ---
+  console.log('\n  2b. temperature in SessionOptions');
+  try {
+    const agent = await Agent.create(KIMI_HCL_CONFIG);
+    const session = await agent.session(cwd, {
+      model: 'openai/kimi-k2.5',
+      temperature: 0.0,
+    });
+    const result = await session.send('Reply with exactly: TEMPERATURE_OK');
+    check('temperature=0.0 accepted', result != null);
+    check('temperature=0.0 has text', Boolean(result?.text),
+      `got: ${result?.text?.slice(0, 80)}`);
+  } catch (e: any) {
+    check('temperature via SessionOptions', false, String(e));
+  }
+
+  // --- 2c: continuationEnabled=false ---
+  console.log('\n  2c. continuationEnabled=false');
+  try {
+    const agent = await Agent.create(KIMI_HCL_CONFIG);
+    const session = await agent.session(cwd, { continuationEnabled: false });
+    const result = await session.send('Reply with exactly: CONT_OK');
+    check('continuationEnabled=false accepted', result != null);
+    check('continuationEnabled=false has text', Boolean(result?.text),
+      `got: ${result?.text?.slice(0, 80)}`);
+  } catch (e: any) {
+    check('continuationEnabled=false', false, String(e));
+  }
+
+  // --- 2d: maxContinuationTurns=1 ---
+  console.log('\n  2d. maxContinuationTurns=1');
+  try {
+    const agent = await Agent.create(KIMI_HCL_CONFIG);
+    const session = await agent.session(cwd, { maxContinuationTurns: 1 });
+    const result = await session.send('Reply with exactly: TURNS_OK');
+    check('maxContinuationTurns=1 accepted', result != null);
+  } catch (e: any) {
+    check('maxContinuationTurns=1', false, String(e));
+  }
+
+  // --- 2e: combined new options ---
+  console.log('\n  2e. Combined new options');
+  try {
+    const agent = await Agent.create(KIMI_HCL_CONFIG);
+    const session = await agent.session(cwd, {
+      model: 'openai/kimi-k2.5',
+      temperature: 0.3,
+      continuationEnabled: true,
+      maxContinuationTurns: 2,
+      maxParseRetries: 3,
+      toolTimeoutMs: 30000,
+      circuitBreakerThreshold: 5,
+    });
+    const result = await session.send('Reply with exactly: COMBINED_OK');
+    check('combined options accepted', result != null);
+    check('combined options has text', Boolean(result?.text),
+      `got: ${result?.text?.slice(0, 80)}`);
+  } catch (e: any) {
+    check('combined options', false, String(e));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  if (!apiKey) {
+    console.log('\n  SKIP: KIMI_API_KEY not set — skipping live LLM tests');
+    skip('live LLM tests', 'KIMI_API_KEY not set');
+  } else {
+    await runLiveTests(apiKey);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Summary
+  // ---------------------------------------------------------------------------
+
+  section('Summary');
+
+  const total = results.length;
+  const passed = results.filter((r) => r.status === 'PASS').length;
+  const failed = results.filter((r) => r.status === 'FAIL').length;
+  const skipped = results.filter((r) => r.status === 'SKIP').length;
+
+  console.log(`\n  Total: ${total}  Passed: ${passed}  Failed: ${failed}  Skipped: ${skipped}`);
+
+  if (failed > 0) {
+    console.log('\n  Failed tests:');
+    for (const { name, status, detail } of results) {
+      if (status === 'FAIL') {
+        console.log(`    ✗ ${name}: ${detail}`);
+      }
+    }
+  }
+
+  console.log();
+  process.exit(failed === 0 ? 0 : 1);
+}
+
+main().catch((e) => {
+  console.error(`Unexpected error: ${e}`);
+  process.exit(1);
+});
diff --git a/sdk/node/index.d.ts b/sdk/node/index.d.ts
@@ -182,6 +182,23 @@ export interface SessionOptions {
   inlineSkills?: Array<InlineSkill>
   /** Override maximum number of tool-call rounds for this session. */
   maxToolRounds?: number
+  /**
+   * Sampling temperature (0.0–1.0). Overrides the provider default.
+   * Only applied when `model` is also set.
+   */
+  temperature?: number
+  /**
+   * Extended thinking token budget (e.g. 10_000). Enables chain-of-thought reasoning.
+   * Only applied when `model` is also set. Provider must support extended thinking.
+   */
+  thinkingBudget?: number
+  /**
+   * Enable continuation injection (default: true).
+   * When enabled, the loop injects a follow-up prompt when the LLM stops without completing.
+   */
+  continuationEnabled?: boolean
+  /** Maximum continuation injections per execution (default: 3). */
+  maxContinuationTurns?: number
   /**
    * Session ID (auto-generated if not set).
    *
@@ -488,6 +505,8 @@ export interface SubAgentConfig {
   workspace?: string
   /** Extra directories to scan for agent definition files */
   agentDirs?: Array<string>
+  /** Extra directories to scan for skill definition files */
+  skillDirs?: Array<string>
   /**
    * Lane queue config for External/Hybrid tool dispatch.
    * When set, tools in the specified lanes are routed to external workers.
@@ -523,6 +542,8 @@ export interface AgentSlot {
   workspace?: string
   /** Extra directories to scan for agent definition files */
   agentDirs?: Array<string>
+  /** Extra directories to scan for skill definition files */
+  skillDirs?: Array<string>
   /** Lane queue config for External/Hybrid tool dispatch */
   laneConfig?: SessionQueueConfig
 }
@@ -574,8 +595,6 @@ export declare class EventStream {
    * When `done` is true, the stream is exhausted.
    */
   next(): Promise<NextResult>
-  /** Async iterator protocol support for `for await...of` loops */
-  [Symbol.asyncIterator](): EventStream
 }
 /**
  * File-backed long-term memory store.
diff --git a/sdk/node/index.js b/sdk/node/index.js
@@ -312,11 +312,6 @@ if (!nativeBinding) {
 
 const { EventStream, FileMemoryStore, FileSessionStore, MemorySessionStore, DefaultSecurityProvider, DocumentParserRegistry, StdioTransport, HttpTransport, WebSocketTransport, UnixSocketTransport, Agent, Session, builtinSkills, TeamTaskBoard, Team, TeamRunner, SubAgentHandle, Orchestrator } = nativeBinding
 
-// Add async iterator support to EventStream
-EventStream.prototype[Symbol.asyncIterator] = function() {
-  return this
-}
-
 module.exports.EventStream = EventStream
 module.exports.FileMemoryStore = FileMemoryStore
 module.exports.FileSessionStore = FileSessionStore
diff --git a/sdk/node/src/lib.rs b/sdk/node/src/lib.rs
@@ -734,6 +734,17 @@ pub struct SessionOptions {
     pub inline_skills: Option<Vec<InlineSkill>>,
     /// Override maximum number of tool-call rounds for this session.
     pub max_tool_rounds: Option<u32>,
+    /// Sampling temperature (0.0–1.0). Overrides the provider default.
+    /// Only applied when `model` is also set.
+    pub temperature: Option<f64>,
+    /// Extended thinking token budget (e.g. 10_000). Enables chain-of-thought reasoning.
+    /// Only applied when `model` is also set. Provider must support extended thinking.
+    pub thinking_budget: Option<u32>,
+    /// Enable continuation injection (default: true).
+    /// When enabled, the loop injects a follow-up prompt when the LLM stops without completing.
+    pub continuation_enabled: Option<bool>,
+    /// Maximum continuation injections per execution (default: 3).
+    pub max_continuation_turns: Option<u32>,
     /// Session ID (auto-generated if not set).
     ///
     /// Set a stable ID so the session can be saved and resumed later:
@@ -1069,6 +1080,18 @@ fn js_session_options_to_rust(options: Option<SessionOptions>) -> RustSessionOpt
     if o.auto_save.unwrap_or(false) {
         opts = opts.with_auto_save(true);
     }
+    if let Some(t) = o.temperature {
+        opts = opts.with_temperature(t as f32);
+    }
+    if let Some(budget) = o.thinking_budget {
+        opts = opts.with_thinking_budget(budget as usize);
+    }
+    if let Some(enabled) = o.continuation_enabled {
+        opts = opts.with_continuation(enabled);
+    }
+    if let Some(turns) = o.max_continuation_turns {
+        opts = opts.with_max_continuation_turns(turns);
+    }
 
     // AHP transport configuration
     #[cfg(feature = "ahp")]
diff --git a/sdk/python/examples/test_api_alignment.py b/sdk/python/examples/test_api_alignment.py
diff --git a/sdk/python/src/lib.rs b/sdk/python/src/lib.rs
