`session.system()`

Example

const system = await session.system();

What It Returns

It returns a structured system snapshot:

{
  sessionId: string;
  session: {
    agentId: string;
    sessionId: string;
    projectRoot: string;
    createdAt: string;
    timezone: string;
  };
  blocks: Array<{
    source: "core" | "instruction" | "service" | "plugin" | "session";
    name: string;
    content: string;
  }>;
}

The blocks can include:

the SDK core fallback, when no instruction was provided
caller-provided static instruction
explicitly injected service system text
registered plugin system text
stable session context, including agentId, sessionId, projectRoot, creation time, and timezone

The returned blocks are the same stable system blocks used by session.prompt().

The session creation time and timezone are the reference time context for the conversation. Dynamic values such as current time should be placed in the user message, not in instruction.

Example Snapshot

{
  "sessionId": "design-review",
  "session": {
    "agentId": "city-dev",
    "sessionId": "design-review",
    "projectRoot": "/path/to/project",
    "createdAt": "2026-05-19T14:16:25.048Z",
    "timezone": "Asia/Shanghai"
  },
  "blocks": [
    {
      "source": "instruction",
      "name": "agent",
      "content": "You are the Downcity project assistant."
    },
    {
      "source": "session",
      "name": "context",
      "content": "当前会话上下文：\n你正在服务 agent \"city-dev\" 的 session \"design-review\"。\n当前项目根目录是 \"/path/to/project\"。\n本会话创建于 2026-05-19T14:16:25.048Z，参考时区是 Asia/Shanghai。\n这个创建时间是当前会话的稳定参考时间，不代表每轮运行时的当前时间。\n如果用户消息中提供了新的当前时间、相对时间或其他动态上下文，应优先使用用户消息中的动态信息。"
    }
  ]
}

What It Does Not Do

session.system() does not write system prompts into messages.jsonl.

Session history stays focused on visible user and assistant messages. Use system() when you need to inspect the prompt context that will be sent alongside that history.