Drive FrontonGPT from your page

Lightweight handshake. Resolves with { extensionVersion } if the content script is alive; rejects after the 2s handshake timeout otherwise. Cheap availability probe — use it to decide whether to render the install-the-extension CTA.

No parameters. No required fields.

const { extensionVersion } = await window.AssistantGPT.ping()

Opens the sidebar, posts a prompt into chat, and streams tokens back via the 'text-delta' event (with matching 'text-start' / 'text-end' lifecycle markers). The promise resolves as soon as the bridge accepts the request; the actual completion happens asynchronously inside the sidebar.

textrequired

string — the prompt the assistant should answer.

template_identifier

string? — pre-canned template the assistant should use (e.g. summarise, translate).

model_identifierone of

string — pick a specific model for this turn (e.g. claude-sonnet, gpt-5-thinking). One of model_identifier / agent_identifier is required.

agent_identifierone of

string — pin a specific agent for this turn (the agent owns its own model). One of model_identifier / agent_identifier is required.

context

object? — structured page state forwarded to the agent (URL, DOI, current section, form values…). Plain JSON only.

Routing requirement. Every processPrompt call must include one of model_identifier (a specific model) or agent_identifier (a pinned agent — the agent then owns its own model). The validator in helpers-extension.js rejects calls that supply neither with a clear error at the call site, so host pages can't accidentally race against an un-initialised sidebar's default selection. Pinning an agent is usually preferable: it keeps tool / instruction / model choice on the server-managed agent row, not on the host code that fires the call.

Always fresh thread. Every call creates a new thread, mirroring openModel / openAgent. There is no opt-out — append-to-current-thread is not supported on this surface. Host pages that want to land a prompt in an existing thread should call openThread({ thread_uid }) instead.

await window.AssistantGPT.processPrompt({
  text: 'Summarise this article for a general audience.',
  agent_identifier: 'submission-assistant', // or model_identifier
  template_identifier: 'summarise',          // optional
  context: { url: location.href },           // optional, plain JSON
})

Opens the sidebar and navigates straight to an existing thread. Useful for deep-links from email digests, audit trails, or any UI that wants to send the user back to the conversation that produced an artefact.

thread_uidrequired

string — the thread to open.

await window.AssistantGPT.openThread({ thread_uid: 'tx-abc123' })

Opens the sidebar with a fresh thread and pre-selects the named agent in the composer. Use to route a visitor straight into the right agent without making them hunt for the picker.

agent_identifierrequired

string — the agent to pin (e.g. submission-assistant).

context

Record<string, unknown> — optional structured context. When provided, the agent opens with a clean, empty chat and the context is attached to the first turn the user sends (no seeded / visible message). This is the recommended way to open an agent pre-loaded with context but a clean chat — unlike processPrompt, which requires non-empty text that renders as a user message.

await window.AssistantGPT.openAgent({ agent_identifier: 'submission-assistant' })

// Context-only launch — clean, empty chat; context rides the first user turn.
await window.AssistantGPT.openAgent({
  agent_identifier: 'submission-assistant',
  context: { url: location.href }, // optional, plain JSON
})

Same shape as openAgent but for models. Spins up a fresh thread so the new model applies in a clean context.

model_identifierrequired

string — the model to pin (e.g. gpt-5-thinking).

context

Record<string, unknown> — optional structured context. When provided, the model opens with a clean, empty chat and the context is attached to the first turn the user sends (no seeded / visible message). Mirrors openAgent's context.

await window.AssistantGPT.openModel({ model_identifier: 'gpt-5-thinking' })

// Context-only launch — clean, empty chat; context rides the first user turn.
await window.AssistantGPT.openModel({
  model_identifier: 'gpt-5-thinking',
  context: { url: location.href }, // optional, plain JSON
})

Opens the sidebar in the current window with no navigation (lands on the default chat tab). Must be called in response to a user gesture (click / keydown) — Chrome consumes the gesture when the panel is currently closed, so calling it outside a gesture handler will fail to open the panel.

No parameters. No required fields.

// Must be called from inside a user-gesture handler.
button.addEventListener('click', () => window.AssistantGPT.open())

Closes the sidebar in the current window. No-op if the panel is already closed.

No parameters. No required fields.

await window.AssistantGPT.close()

Opens the sidebar and pre-selects the named skill in the composer. The skill is a composer adornment (not a routing target), so this applies to the active session rather than spinning up a fresh thread. No-op if the skill isn't in the workspace's skill catalog.

skill_namerequired

string — the skill to pre-select (matches the skill's display name).

await window.AssistantGPT.openSkill({ skill_name: 'Literature review' })

Same shape as openSkill but pre-selects a prompt template in the composer, matched by its identifier. No-op if the identifier isn't in the prompt-template catalog.

template_identifierrequired

string — the prompt template to pre-select (e.g. summarise).

await window.AssistantGPT.openTemplate({ template_identifier: 'summarise' })

"processPrompt that stops before sending": drops the given text into the composer without firing a turn — the user reviews / edits before hitting send. Replaces any existing draft. Accepts the same optional setup fields as processPrompt.

textrequired

string — the draft to drop into the composer.

model_identifier

string? — optional model to pin. Routing is optional here (no turn is fired); when supplied, a fresh thread opens so the model applies cleanly. Model wins if both model + agent are given.

agent_identifier

string? — optional agent to pin; also opens a fresh thread when supplied.

template_identifier

string? — optional prompt template to preselect.

context

Record<string, unknown> — optional structured context stashed on the session; it rides the turn the user sends after reviewing / editing the draft. With no routing fields the draft lands in the active thread.

// Draft into the ACTIVE thread (no routing) — user reviews & sends.
await window.AssistantGPT.prefillPrompt({ text: 'Draft a reply to this thread.' })

// "processPrompt that stops before sending": same fields, but nothing
// is sent. A model/agent opens a FRESH thread with that route pinned;
// context rides the turn the user sends after editing the draft.
await window.AssistantGPT.prefillPrompt({
  text: 'Summarise the article I am looking at.',
  agent_identifier: 'submission-assistant', // or model_identifier
  template_identifier: 'summarise',          // optional
  context: { url: location.href },           // optional, plain JSON
})

Subscribe to events the extension fires back to the host page. on() returns an unsubscribe function for convenience; off() works too. Pure synchronous registration — no promise.

The 'text-*' events mirror AI SDK v5's stream-part naming so adopters who already consume AI SDK streams recognise the shape.

'text-start'

Fires once at the open of each streaming turn from a processPrompt call from this page. Handler receives { id }. Use to flip a "typing…" indicator, lock a form, start an analytics timer.

'text-delta'

Streamed token deltas from the most recent processPrompt. Handler receives { id, content }. Fires many times per turn, between matching 'text-start' / 'text-end' markers.

'text-end'

Fires once when the streaming turn completes (cleanly or on error). Handler receives { id }. Always preceded by exactly one 'text-start' for the same id.

'event'

An LLM-driven host event from the Host Events tool. Unlike every other event, the handler receives (name, data, reply) — not a single detail object. emit_host_event is fire-and-forget (ignore reply); request_host_event is two-way — call reply(payload) to send a value back to the agent (first-wins). Fires for any sidebar chat, delivered to whichever tab is active when the event fires.

'disconnected'

Fired when the extension context is invalidated mid-page (user updated the extension, browser killed the process). Host page should fall back to the install/refresh CTA.

// Streamed-answer lifecycle (single detail object per event).
const off = window.AssistantGPT.on('text-delta', ({ id, content }) => {
  transcript += content
})

// LLM-driven host events get the special (name, data, reply) shape.
window.AssistantGPT.on('event', (name, data, reply) => {
  if (name === 'get_user_role') reply(currentUser?.role ?? null)
})

window.AssistantGPT.on('disconnected', () => showInstallCta())

off() // unsubscribe (or: AssistantGPT.off('text-delta', handler))