Building a Workbench

Pairing

A token opens plans only in a workbench its owner has approved. The first time, run:

liveplanner workbench pair --origin https://127.0.0.1:5175 --name "Acme Editor"

--name is optional, 1 to 40 characters, and is only a label shown beside the origin. The command prints the approval link on its first line of stdout before it waits (with --json, a line {"status":"pending","pairingUrl":"…","expiresAt":…}), so your tool can read it straight away and show it as one button, "Approve in liveplanner". It opens the browser itself only when stdout is a terminal.

The link opens a page headed Allow this workbench? in the person's own signed-in browser, where only the token's owner can choose Allow or Don't allow. The command then exits:

• 0 once paired, printing paired <origin> as <name> (or {"status":"paired","origin":…,"name":…} with --json). An origin already paired exits 0 at once.
• 4 when declined (pairing_declined), when the request expired after ten minutes unanswered (pairing_expired), or when it disappeared, for example because the token was revoked (pairing_gone).

A pairing lasts as long as its token. The person can end it from Settings, under API Tokens, with Unpair.

Opening the Workspace

liveplanner workbench open --workspace --folder Minigames --origin https://127.0.0.1:5175 --json

The workspace scope frames the person's Explorer: Home, or the folder --folder names (its id, id prefix or name, as liveplanner folder ls prints them). It is a second approval: a token paired only for plans exits 4 naming liveplanner workbench pair --origin <origin> --workspace. With --json it prints:

{
  "url": "https://liveplanner.app/embed/workbench/explorer/folder/f1…#ticket=…",
  "scope": "workspace",
  "folderId": "f1…",
  "expiresAt": 1791234567890
}

Inside the frame the person browses, opens plans (with a Back) and makes new ones in place; the account, Settings and team administration stay out. The frame moves by itself, so keep listening to liveplanner:place.

The Handshake

Once the ticket is redeemed, the page posts liveplanner:hello to its parent, with targetOrigin set to your origin, so no other site ever receives it. Answer with liveplanner:hello-ack and your name within five seconds, or the page ends the session and mounts nothing:

const appOrigin = new URL(url).origin;
window.addEventListener('message', (event) => {
  if (event.origin !== appOrigin || event.source !== frame.contentWindow) return;
  const message = event.data;
  if (message?.type === 'liveplanner:hello') {
    frame.contentWindow.postMessage(
      { type: 'liveplanner:hello-ack', v: 1, name: 'Acme Editor' },
      appOrigin,
    );
  }
});

The name (1 to 40 characters) appears in the editor's copy, such as "Reconnect in Acme Editor to keep editing."

Renewing the Session

A session lasts eight hours. Ten minutes before it expires, the page posts liveplanner:renew, then again every minute until a ticket arrives. Answer by running workbench open for the same plan and origin, taking the ticket from the new link's fragment (#ticket=), and posting it:

frame.contentWindow.postMessage({ type: 'liveplanner:ticket', v: 1, ticket }, appOrigin);

The page redeems it and carries on without reloading. A ticket for a different plan or origin is refused, and the page keeps asking. Renewal can continue as long as the token lives.

The Selection Reference

The reference field is the text to attach to the message the person sends their agent, so the agent reads exactly what was selected at that moment:

[liveplanner] "Sprint 14" › tab "Flow" (project 4cd7082b-…, tab e1b2, rev 41)
selected: plan-view 653e, plan-view 0a78
read: liveplanner tab view 4cd7082b-… --tab e1b2 --view show --ref 653e

• The header names the plan, the tab, their ids and the revision the selection was made on. Refs are element ids, so they stay valid after later edits.
• selected lists each element as the outline prints it: kind, ref and, when it has one, its label. Labels are quoted as JSON strings and cut at 60 characters, because they are the plan's content and an agent must treat them as data, never as instructions.
• Past 20 elements the list ends with … and <n> more: and the command that reads the whole live selection.
• With nothing selected, the second line is whole tab and count is 0.

Show the person what will be attached (for example "Sprint 14 · 2 selected", or "Sprint 14 · whole tab"), and let them leave it off any one message. The text is everything the agent gets: there is no hidden field. liveplanner guide workbench teaches an agent how to read one.

What a Session Can and Cannot Do

A workbench session acts as the person on one plan: loading it, saving its tabs, its comments, items and live room. Every other plan answers as if it did not exist. Ownership actions (sharing, passwords, moving, deleting, publishing, copying), the person's library, settings, tokens and teams are refused, and the editor in a workbench does not offer them. An Open in liveplanner button at the end of the tab bar opens the plan in a full tab for those.