`session.system()`

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" | "plugin" | "session";
    name: string;
    content: string;
  }>;
}

The blocks can include:

caller-provided static instruction
Downcity Agent core guidance, including Harness design, Shell command rules, and plugin system rules
registered and enabled plugin system text
stable session context, including agent_id, 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 plugin 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:

instruction: the host-provided Agent role, business rules, and response preferences.
core: fixed Downcity Agent runtime guidance, including Harness design, Shell command rules, and plugin system rules.
plugin: each enabled, ready, and currently available plugin's own system prompt.
session: stable context for the current session.

Even when the host provides instruction, core is still injected immediately after it.

Example Snapshot

{
  "session_id": "design-review",
  "session": {
    "agent_id": "city-dev",
    "session_id": "design-review",
    "project_root": "/path/to/project",
    "created_at": "2026-05-19T14:16:25.048Z",
    "timezone": "Asia/Shanghai"
  },
  "blocks": [
    {
      "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\nCommand execution tools:\n- Prefer `shell_exec` for short, one-off commands.\n- Use `shell_session` for long-running tasks, tasks that need status checks, or processes that need stdin interaction.\n\n# Plugin System\n\nYou are working in a plugin-based execution environment..."
    },
    {
      "source": "plugin",
      "name": "task",
      "content": "# Task Plugin\n\nThe task plugin manages scheduled and repeatable tasks..."
    },
    {
      "source": "session",
      "name": "context",
      "content": "Current session context:\nYou are serving agent \"city-dev\" in session \"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 active.jsonl or historical Segments.

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.

session.system()