Session Control - Qoder CN

By default the SDK starts a brand-new session on every call (TypeScript's query()) or connection (Python's QoderSDKClient). A few fields in options let you specify a session ID, resume a historical session, or fork an existing one.

Concepts

A session corresponds to a persisted conversation history on the CLI side (including context, tool call records, compaction boundaries, etc.), identified by a UUID. The init system message contains the current session_id, which also serves as the anchor point for subsequent resume/fork operations. The authentication in the examples below can be replaced with whichever method your project uses; see SDK Authentication.

Creating New Sessions

Default

Without passing any session-related fields, a new session is created each time:

import { accessTokenFromEnv, query } from '@qodercn-ai/qodercn-agent-sdk';

const q = query({
  prompt: 'Hello',
  options: { auth: accessTokenFromEnv() },
});

Specifying a Session ID

Let the caller determine the session UUID (suitable when the host manages its own session index):

import { randomUUID } from 'node:crypto';

const sessionId = randomUUID();
const q = query({
  prompt: 'Hello',
  options: {
    auth: accessTokenFromEnv(),
    sessionId,
  },
});

Resuming Sessions

Resume by ID

const q = query({
  prompt: 'Continue the previous conversation',
  options: {
    auth: accessTokenFromEnv(),
    resume: 'previous-session-id',
  },
});

Resume the Most Recent

When you don't know the session ID, use continue: true (TypeScript) / continue_conversation=True (Python) to pick up the most recently modified session:

const q = query({
  prompt: 'Continue',
  options: {
    auth: accessTokenFromEnv(),
    continue: true,
  },
});

Do not pass resume together with continue (continue_conversation in Python).

Forking Sessions

Derive a new session from an existing one, preserving the original context but obtaining a new session ID. The original session is unaffected:

const q = query({
  prompt: 'Based on the prior context, explore a different direction',
  options: {
    auth: accessTokenFromEnv(),
    resume: 'source-session-id',
    forkSession: true,
  },
});

To specify an ID for the forked new session:

options: {
  auth: accessTokenFromEnv(),
  resume: 'source-session-id',
  forkSession: true,
  sessionId: 'my-new-session-id',
}

Field Reference

Field (TypeScript / Python)	Type	Behavior
`sessionId` / `session_id`	`string` / `str`	Alone: create a new session with this ID; with the fork field: the ID of the forked session
`resume` / `resume`	`string` / `str`	The session ID to resume
`continue` / `continue_conversation`	`boolean` / `bool`	`true` resumes the most recent session
`forkSession` / `fork_session`	`boolean` / `bool`	Used with `resume` to fork instead of continuing

Getting the Current Session ID

Listen for the init system message; in Python, ResultMessage also carries session_id—either works for bookkeeping:

for await (const msg of q) {
  if (msg.type === 'system' && msg.subtype === 'init') {
    console.log('session_id:', msg.session_id);
  }
}

User data directory

The user data directory stores session history, resources, logs, and other user-level CLI data. Set QODERCN_CONFIG_DIR through options.env to select this directory:

import { accessTokenFromEnv, query } from '@qodercn-ai/qodercn-agent-sdk';

const q = query({
  prompt: 'Analyze this repository',
  options: {
    auth: accessTokenFromEnv(),
    env: {
      ...process.env,
      QODERCN_CONFIG_DIR: '/var/lib/my-agent/qoder',
    },
  },
});

​Concepts

​Creating New Sessions

​Default

​Specifying a Session ID

​Resuming Sessions

​Resume by ID

​Resume the Most Recent

​Forking Sessions

​Field Reference

​Getting the Current Session ID

​User data directory