session.system()

Read the structured system prompt snapshot currently active for a session

Example

const system = await session.system();

What It Returns

It returns a structured system snapshot:

{
  session_id: string;
  session: {
    agent_id: string;
    session_id: string;
    project_root: string;
    created_at: string;
    timezone: string;
  };
  blocks: Array<{
    source: "core" | "instruction" | "power" | "session";
    name: string;
    content: string;
  }>;
}

The blocks can include:

  • the Agent identity block, carrying the Agent name and id
  • caller-provided static instruction
  • Downcity Agent core guidance, including Harness design, Shell command rules, and power system rules
  • registered and enabled power system text
  • stable session context, including session_id, project_root, creation time, and timezone

The returned blocks are the same stable system blocks used by session.prompt(). The first generated system is fixed in the Session's memory; later Agent instruction or power registry changes do not alter it. Newly created Sessions use the latest configuration.

To explicitly adopt the Agent's current configuration in an existing local Session, call session.syncshot().

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.

Block Order

@downcity/agent builds system blocks in a fixed order:

  1. instruction / identity: the Agent name and id, injected by the SDK. The Agent identity is stable across every Session of that Agent.
  2. instruction / agent: the host-provided Agent role, business rules, and response preferences.
  3. core: fixed Downcity Agent runtime guidance, including Harness design, Shell command rules, and power system rules.
  4. power: each enabled, ready, and currently available power's own system prompt.
  5. session: stable context for the current session.

Even when the host provides instruction, core is still injected immediately after it. The session block describes the session itself and does not repeat the Agent identity.

Example Snapshot

{
  "session_id": "design-review",
  "session": {
    "agent_id": "reviewer",
    "session_id": "design-review",
    "project_root": "/path/to/project",
    "created_at": "2026-05-19T14:16:25.048Z",
    "timezone": "Asia/Shanghai"
  },
  "blocks": [
    {
      "source": "instruction",
      "name": "identity",
      "content": "# Agent Identity\n\nYou are \"Code Reviewer\" (agent id: reviewer)."
    },
    {
      "source": "instruction",
      "name": "agent",
      "content": "You are the Downcity project assistant."
    },
    {
      "source": "core",
      "name": "default",
      "content": "# Downcity Agent\n\nYou are a Downcity Agent running inside the Downcity Agent runtime...\n\n# Harness Design\n\nDowncity Agent is a harness around an existing human-owned workspace, not a replacement platform...\n\n# Shell Commands\n\nAll Shell work goes through the `shell` power...\n\n# Power System\n\nYou are working in a power-based execution environment..."
    },
    {
      "source": "power",
      "name": "task",
      "content": "# Task Power\n\nYou can use the `task` power to manage task definitions, execution, scheduling, and status control..."
    },
    {
      "source": "session",
      "name": "context",
      "content": "Current session context:\nThis session is \"design-review\".\nThe current project root is \"/path/to/project\".\nThis session was created at 2026-05-19T14:16:25.048Z, with Asia/Shanghai as its reference timezone.\nThis creation time is a stable reference for the session and does not represent the current time for every run.\nIf the user message provides a newer current time, a relative time, or other dynamic context, prioritize the dynamic information from the user message."
    }
  ]
}

What It Does Not Do

session.system() does not write system prompts into canonical Message history.

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.