Tools: sites and turns

These tools find your sites, open and close turns, and show what's happening on a site. See the Tool reference for conventions and shared errors.

list_sites

Lists every site you can access across all your workspaces, with each site's ID, address name (slug), name, workspace ID and name, and when it was last edited.

When to use it: First, to find the siteId for the site the user means.

Needs an open turn: No.

No inputs.

Example call

{}

Example result

{
  "ok": true,
  "sites": [
    {
      "id": "0APMiuxGY2yB4xJm5BilJ",
      "slug": "bakery",
      "name": "Bakery",
      "orgId": "org_…",
      "orgName": "Dana's workspace",
      "lastEditedAt": "2026-10-17T21:38:22.739Z"
    }
  ]
}

Errors

You see	What it means	What to do
"list_sites failed: …"	Starjay couldn't load your sites.	Retry in a moment.

get_session_state

Shows the site's AI session and who, if anyone, holds the site right now.

When to use it: Before start_turn, to see whether the user, Starjay's built-in AI or another agent is working. Also useful for polling.

Needs an open turn: No.

No inputs besides siteId.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ"
}

Example result

{
  "active": true,
  "sessionId": "sess_…",
  "currentIterationId": "iter_…",
  "lastTurnAt": "2026-10-17T21:40:22.634Z",
  "lockHolder": {
    "kind": "external",
    "id": "…",
    "source": "external",
    "acquiredAt": "2026-10-17T21:53:29.038Z",
    "expiresAt": "2026-10-17T22:01:43.322Z"
  },
  "generationId": 3,
  "turnCount": 0,
  "canvasLocked": true,
  "userEditable": false,
  "lastTurnWriteCount": 0
}

active is true while there's an AI session waiting for Save or Reject. lockHolder is null when nobody holds the site; kind is external for a connected agent and in_product for Starjay's built-in AI.

start_turn

Opens a turn: reserves the site for your agent so it can make changes. On a site with no AI session, it first takes a checkpoint and starts a new session. If your agent already holds an unfinished turn on the site, start_turn resumes it.

When to use it: Before the first change, and again after end_turn when there's more to do.

Needs an open turn: No. It opens one.

Input	Type	Required	Meaning
prompt	string	No	The user's request. It's recorded in the session's chat so the user sees what the turn is for.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ",
  "prompt": "Make the hero headline shorter"
}

Example result

{
  "ok": true,
  "turnId": "4",
  "sessionId": "sess_…",
  "iterationCount": 2
}

Errors

You see	What it means	What to do
session_locked	Someone else holds the site: the user, the built-in AI, or another agent. retryAfterSeconds says when to try again.	Wait and retry, or ask the user to finish what they're doing.
site_publishing	The site is publishing.	Wait for the publish to finish, then retry.
snapshot_unavailable	Starjay couldn't take the safety checkpoint, so it won't allow changes.	Retry after a few seconds.
org_concurrent_session_limit_exceeded	Too many AI sessions are running in this workspace at once.	Wait for another to finish, then retry.

end_turn

Closes the turn. Everything written during the turn becomes one version in the session, and the site is released so the user can review it.

When to use it: When you've finished a piece of work. Then tell the user to review it in the editor and click Save or Reject.

Needs an open turn: Must hold one.

Input	Type	Required	Meaning
summary	string	No	A short description of what the turn changed. It's shown on the version.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ",
  "summary": "Shortened the hero headline"
}

Example result

{
  "ok": true,
  "iterationId": "iter_…",
  "filesWritten": [
    "src/components/sections/Hero.astro",
    "brand/tokens.ts",
    "brand/theme.css"
  ],
  "autoTokenized": {
    "files": [
      "brand/tokens.ts",
      "brand/theme.css"
    ],
    "surfaced": [
      "red"
    ]
  }
}

If the turn used a Tailwind color or a raw color that isn't one of the site's colors yet, Starjay adds it as a site color automatically. Those files and colors are listed under autoTokenized.

Errors

You see	What it means	What to do
not_lock_holder: "No active turn — call start_turn first"	There's no open turn.	Nothing to close. Call start_turn before making changes.
not_lock_holder: "Turn lease expired …"	The turn lapsed while your agent was idle.	Call start_turn, then end_turn again.
no_active_session	The session ended during the turn (for example, the user saved or rejected).	Call get_session_state and start again if needed.
snapshot_unavailable	Starjay couldn't record the version.	Call end_turn again.

cancel_turn

Asks whoever holds the site to stop. It works on any open turn, including the built-in AI's. Changes already made stay in the session until the user rejects them.

When to use it: When the user asks you to stop work that's in progress.

Needs an open turn: No.

No inputs besides siteId.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ"
}

Example result

{
  "accepted": true,
  "holdingTier": "external"
}

holdingTier is who held the site when you cancelled, or null if nobody did.

get_recent_changes

Lists the session's recent versions, newest first, with the files each one changed and its summary.

When to use it: To catch up on what changed since you last looked, including the user's own edits.

Needs an open turn: No.

Input	Type	Required	Meaning
sinceIterationId	string	No	Return versions after this one. Use nextCursor from the previous result.
limit	number	No	How many to return. Default 50, maximum 200.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ",
  "limit": 1
}

Example result

{
  "iterations": [
    {
      "id": "iter_…",
      "parentIterationId": null,
      "source": "external",
      "filesChanged": [
        "src/pages/about.astro"
      ],
      "turnSummary": "Added an About page",
      "createdAt": "2026-10-17T19:55:51.094Z"
    }
  ],
  "nextCursor": "iter_…"
}

get_editor_focus

Shows what the user has selected in the editor right now: the page, component and element, with a pointer to the exact place in the source.

When to use it: When the user says "this section" or "fix this" and you need to know what they mean.

Needs an open turn: No.

No inputs besides siteId.

Example call

{
  "siteId": "0APMiuxGY2yB4xJm5BilJ"
}

Example result

{
  "focus": null
}

It returns {"focus": null} when the user doesn't have the site open in the editor, or hasn't interacted with it in the last 30 seconds. Ask the user to click the element and try again. It only ever returns your own selection, never another member's.

Related

• How agent work shows up in the editor
• Tools: reading your site