Skip to content
Troy

Troy / Reference

Engine and bridge API

Reference for Troy's internal surfaces: the Cdp port, the window.troy and new tab bridges, the main-process modules and the read pipeline modules.

On this page
  1. The Cdp port
  2. Obtaining one
  3. The chrome bridge: window.troy
  4. The new tab bridge: window.troyNewTab
  5. Main-process modules
  6. The read pipeline modules (main)
  7. The agent modules (main)

Troy has no published library or npm package. This page documents the programming surfaces inside the repository, for contributors and for anyone reading the code. The external interface for agents is the Chrome DevTools Protocol (CDP), unchanged, covered in Driving Troy from an agent.

Each surface is kept narrow on purpose. Code that needs only a few capabilities asks for only those, so it can be tested without a browser and reused by every host that can supply them.

The Cdp port

src/cdp/types.ts defines a narrow interface over one CDP session, so the same code can run under Playwright or against a live Electron tab. Its methods:

interface Cdp {
  send<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>
  on(event: string, handler: (params: unknown) => void): () => void
  screenshot(clip?: Box): Promise<Buffer>
  evaluate<T>(fn: string): Promise<T>
  url(): Promise<string>
  close(): Promise<void>
}

type Box = { x: number; y: number; w: number; h: number }
  • send sends a raw CDP command. For Page.navigate it also waits for Page.loadEventFired or Page.navigatedWithinDocument, and resolves (never rejects) after a timeout of 30000 ms if neither arrives. Pass timeoutMs in params to change it. The result does not say which case happened; check document.readyState if it matters.
  • on subscribes to a CDP event and returns an unsubscribe function.
  • screenshot returns a Portable Network Graphics (PNG) image, optionally clipped to a box.
  • evaluate runs an expression with Runtime.evaluate and returns the value. A thrown exception becomes an Error with the exception’s description.
  • url returns the page address. On main it asks the page for location.href, which includes hash changes and pushState updates, and falls back to Playwright’s cached address.
  • close releases the session; what that means depends on how it was obtained.

Obtaining one

src/cdp/playwright.ts exports three constructors:

Function Browser close() does
launchHeadless() New headless Chromium Closes that browser
connectOverWs(url) An already running browser Detaches only
launchPersistent(dir) Chromium on a profile dir Closes the browser

connectOverWs never closes the browser it attached to, because that browser may hold a signed-in session. It uses the first context and first page, opening one if none exists. On main its close() also drops Playwright’s connection handle, which for a CDP connection disconnects without ending the browser.

Only Cdp is exported from these functions; Playwright types do not leak through the port. listenerCountForTests is a test-only helper.

The test suite uses these to drive real Chromium. On main, the read pipeline asks for an even narrower port (below), which a Cdp satisfies as is.

The chrome bridge: window.troy

The chrome page (tab strip, toolbar, agent panel) talks to the main process only through src/browser/preload.cjs, which exposes a fixed object on window.troy. Its types are written down in src/browser/bridge.d.ts.

Actions:

  • newTab(url?), selectTab(id), closeTab(id)
  • back(), forward(), reload()
  • go(input): resolve and load, returns { kind, reason? } where kind is url, search, external, refused or empty
  • togglePanel(): returns whether the panel is now open
  • read(): reads the active tab, or returns { error }

In v0.1.5, read() returns { url, text, degraded }. On main it runs the read pipeline and returns:

  • url, title
  • blockCount, domBlockCount, ocrBlockCount, regionCount
  • characterCount, elapsedMs
  • settled, degraded (true when settle timed out)
  • ocrEngine ("none" when no engine ran)
  • markdown, the page rendered as Markdown

Subscriptions, each returning an unsubscribe function:

  • onTabs(handler): receives { tabs, canGoBack, canGoForward, loading, panelOpen }. Each tab has id, title, url, favicon, failed, loading, active.
  • onNotice(handler): a sentence to show the user.
  • onFocusOmnibox(handler): the Focus Address Bar menu item fired.

The new tab bridge: window.troyNewTab

src/browser/tab-preload.cjs is attached to every tab but exposes window.troyNewTab only on Troy’s own new tab page. The main process also checks the calling frame’s address on each of these channels and throws for any other page. The preload’s check is tidiness; the main process check is the guarantee, because a page cannot lie about the address of the frame it calls from.

On main:

  • state(): { rememberHistory, blockTrackers }
  • setSetting(key, value): only rememberHistory and blockTrackers

v0.1.5 also has the shortcut channels, and state() includes shortcuts:

  • addShortcut(url, title?), removeShortcut(url): return the updated list
  • open(url): opens a tile through the address bar rules

Main-process modules

Each is a plain module that can be tested without launching a browser.

  • omnibox.js: resolveOmnibox(input, { search }), ENGINES
  • tracking.js: stripTrackingParams, isTrackerHost, shouldBlockRequest, installBlocker, TRACKING_PARAMS, TRACKER_HOSTS
  • settings.js: defaults, settingsFile, readSettings, writeSettings
  • shortcuts.js: MAX_SHORTCUTS (12), readShortcuts, writeShortcuts, addShortcut, removeShortcut, normalise. On main the file remains but the app no longer imports it.
  • history.js (main): MAX_HISTORY (500), historyFile, readHistory, writeHistory, recordVisit, clearHistory
  • readPort.js (main): readTab(webContents, { settleTimeoutMs? }) runs the read pipeline on a live tab, attaching the debugger only for the read; summariseDocument(doc) builds the panel’s read() result
  • extensions.js: findExtensions, readManifest, loadExtensions, summarise
  • resilience.js: installSafetyNet, formatError, appendLog
  • endpoint.js: endpointFile, describeEndpoint, writeEndpoint, readEndpoint, clearEndpoint

The read pipeline modules (main)

The pipeline is plain JavaScript with types in JSDoc comments, so Electron’s main process and the scripts can import it with no build step. It asks for a ReadPort: an object with evaluate(expression) returning a promise of the result, and an optional screenshot(box) returning a promise of PNG bytes. Without screenshot, a read still returns everything the Document Object Model (DOM) explains.

  • pipeline.js: readPage(port, { settleTimeoutMs?, ocr? }) returns a ReadDocument. settleTimeoutMs defaults to 10000; ocr defaults to the stub engine.
  • settle.js: settle(evaluate, opts), settleProbeExpression(reset)
  • extract.js: extract(evaluate), extractExpression()
  • cover.js: cover(candidates, blocks, viewport), a pure function
  • ocr.js: stubEngine(), transcribe(port, regions, engine)
  • apple-vision.js: appleVisionEngine(), macOS only
  • fuse.js: fuse(domBlocks, ocrBlocks), columnsOf(items)
  • render.js: toMarkdown(doc)
  • types.js: the shared shapes (Box, DomBlock, CoverCandidate, CoverRegion, OcrLine, OcrEngine, FusedBlock, Extraction, ReadDocument)

An optical character recognition (OCR) engine is any object with name, available() and recognize(png), where recognize returns lines of { text, box, confidence } in image pixels. The pipeline asks available() before taking any screenshot, and a failing engine degrades to untranscribed markers instead of failing the read. Field-by-field output is on How Troy reads a page.

The agent modules (main)

src/agent/ holds the tool layer, the model loop and the key store. None of it is wired into the app yet. See Agent tool layer.