User Browser (deprecated) (user-browser)

Category: tools | Form: | Symbol: Ub

Legacy: pre-unification shape of a paired user browser. Superseded by browser with backend=user-extension.

DEPRECATED. This is the pre-unification shape of a paired user browser. New pairings create browser elements with spec.backend=“user-extension” instead; the behaviour is identical (same ops, same WS bridge, same offscreen/tab visibility). Legacy rows of this type still dispatch correctly through the OperationDispatcher. Do not create new user-browser elements — they’ll be orphaned by the next cleanup pass.

Guide

Status: deprecated. Use tools/browser with spec.backend = "user-extension" instead. This element type is kept in the registry only so legacy rows created before the unification keep dispatching. The directory will be deleted once no rows of this type remain in any circle.

Historically connected to the user’s real Chrome browser via the Triform Connect extension. Superseded by the unified browser element type with a pluggable backend property (browserless | user-extension | stealth). All behaviours described below are now available on browser when backend = "user-extension" — same ops, same WS bridge, same visibility modes (offscreen | tab).

Overview (legacy)

The user-browser element bridges agents to the user’s actual Chrome browser through a persistent WebSocket connection managed by the Triform Connect extension. Unlike the headless browser element, user-browser has access to real authentication state — cookies (including HttpOnly), localStorage, sessionStorage, and can execute fetch requests with the user’s full session credentials.

Quick Start

# 1. Install the Triform Connect Chrome extension
# 2. Connect it to your circle (authenticates via WebSocket)

# 3. Create a user-browser element
POST /api/my-circle/tools/user-browser/ {
  "slug": "my-session",
  "name": "My Browser Session",
  "spec": { "sync_cookies": true, "allowed_domains": ["github.com"] }
}

# 4. Attach to an agent
POST /api/my-circle/tools/user-browser/my-session/ops/attach {
  "target_id": "<agent-uuid>"
}

# 5. Agent now has 8 browser tools including authenticated fetch

Properties

Property	Type	Default	Description
sync_cookies	boolean	true	Auto-sync cookies from connected browser
allowed_domains	string[]	[]	Restrict cookie sync to these domains (empty = all)
url	string	""	Current URL in connected browser tab
session_id	string	""	Explicit session ID for sharing (auto-generated if empty)
timeout_ms	u32	30000	Operation timeout (1000–120000 ms)
tool_names	string[]	8 tools	Tool names injected when attached to agents

Operations

Operation	Method	Description
navigate	POST	Navigate to URL in connected browser
content	POST	Get HTML content of current page
click	POST	Click element by CSS selector via content script
type_text	POST	Type text into input via content script
screenshot	POST	Capture visible tab screenshot (PNG)
cookies	POST	Get cookies for a domain (including HttpOnly)
storage	POST	Get localStorage/sessionStorage for an origin
fetch	POST	Execute HTTP request with browser’s session

Fetch (Most Powerful Operation)

The fetch operation executes HTTP requests inside the user’s real browser context:

POST /api/my-circle/tools/user-browser/my-session/ops/fetch {
  "url": "https://api.github.com/user",
  "method": "GET",
  "credentials": "include"
}
# Returns: { "status": 200, "headers": {...}, "body": {...} }

• credentials: "include" (default) — sends all cookies and auth headers
• 30s timeout per request
• Supports any HTTP method, custom headers, and request body
• Use this for authenticated API calls that server-side requests can’t make

Cookies

POST /api/my-circle/tools/user-browser/my-session/ops/cookies {
  "domain": "github.com"
}

• Reads from in-memory cookie jar first (synced via cookie_delta messages)
• Falls back to fresh request from extension (5s timeout)
• Includes HttpOnly cookies that JavaScript cannot access
• Cookie jar limited to 10,000 entries

Storage

POST /api/my-circle/tools/user-browser/my-session/ops/storage {
  "origin": "https://github.com"
}

• Origin must be a full URL (e.g., https://example.com), not just a domain
• Requires an open tab on that origin

Architecture

The extension communicates via WebSocket through browser_bridge.rs:

Chrome Extension ←→ WebSocket ←→ BrowserBridgeRegistry ←→ Agent Tools
                                  (per-circle handle)

Protocol Messages

Extension → Server: authenticate, cookie_sync, cookie_delta, cookie_response, storage_response, fetch_response, click_response, type_response, screenshot_response

Server → Extension: authenticated, request_cookies, request_storage, execute_fetch, execute_click, execute_type, execute_screenshot

Request/Response Correlation

All operations use UUID request_id for correlation:

1. Server sends command with request_id via WebSocket
2. Extension processes and sends response with same request_id
3. Server resolves the oneshot::Sender in BridgeResponseWaiters

Modifier Behavior

Field	Value
applies_to	actors, frontend
cascade_behavior	nearest
fail_action	allow
evaluation_order	50

When to Use

• Use user-browser when: the target requires authentication, OAuth sessions, or API keys stored in cookies
• Use browser (headless) instead when: the site is public and doesn’t need auth

Errors

Code	Class	Retryable	Description
BROWSER_NOT_CONNECTED	conflict	Yes	No extension connected for this circle
BROWSER_TIMEOUT	timeout	Yes	Operation timed out (30s for fetch, 5s for cookies)
BROWSER_FETCH_FAILED	internal	Yes	Fetch request failed
BROWSER_NO_MATCHING_TAB	not_found	No	No open tab matches the requested origin

Relationships

• Attaches to: function, triformer, condition, evaluator, loop, wait, hitl, view, spa, ssr
• Uses: variable

Capabilities

• executable: Element can be invoked to execute operations
• session-browsing: Browse web pages using the user’s authenticated browser sessions
• cookie-access: Read cookies including HttpOnly from the connected browser
• storage-access: Read localStorage and sessionStorage from open tabs
• session-fetch: Execute HTTP requests using the browser’s session and cookies
• dom-interaction: Click elements and type text via content scripts
• screenshots: Capture visible tab screenshots

Properties

Property	Type	Default	Description
tool_names	array	["browser_navigate","browser_content","browser_screenshot","browser_click","browser_type","browser_cookies","browser_storage","browser_fetch"]	Built-in tool names this element provides to attached agents
agent_instructions	string	""	Core skill guide injected on first tool use. Teaches the agent how to use Triform Connect browser tools. Source: skills/SKILL.md
skill_references	object	{}	Reference guides for advanced topics. Keyed by topic name, served via the help command.
sync_cookies	boolean	true	Automatically sync cookies from the connected browser
allowed_domains	array	[]	Only sync cookies for these domains (empty = all domains)
url	string	""	Current URL in the connected browser tab (must be a valid URI)
current_title	string	""	Title of the current page
session_id	string	""	Explicit session ID for sharing sessions across elements (auto-generated if empty)
timeout_ms	integer	30000	Operation timeout in milliseconds
device_fingerprint	string	""	Stable fingerprint identifying this physical browser within a circle. blake3(owner_id || browser_name || os || machine_hint). Populated at enrollment; used to reuse the same element across reconnects and reinstalls.
user_agent	string	""	Raw User-Agent string reported by the extension at pairing/reconnect time.
os	string	""	Operating system as reported by chrome.runtime.getPlatformInfo (e.g. macos, windows, linux, chromeos)
browser_name	string	""	Browser engine/brand (chrome, firefox, edge, brave, arc, …)
extension_version	string	""	Version string of the installed Triform Connect extension (from manifest.json).
device_name	string	""	Human-friendly name for this browser (e.g. ‘Chrome · MacBook Air’). Shown in the Devices tab. Derived at enrollment, user-editable.
first_seen_at	string	""	UTC timestamp when this browser first paired with the circle.
last_seen_at	string	""	UTC timestamp of the most recent authenticate / keepalive / op from this browser.
connected_replica	string	""	Hostname of the physics replica currently holding the extension’s WebSocket. Used by other replicas to forward ops. Cleared on disconnect.

Operations

activity

Get /ops/activity | Auth: Read

Get activity events for this element

Scope depends on element capabilities: individual elements query by element_id, project-form elements with activity-scope-members include member activities, circle-level elements with activity-scope-all query the entire circle. Gracefully returns empty list if activities table is missing (old circles).

attach

Post /ops/attach | Auth: Read

Attach this tool to a target agent element

This is the critical operation that grants an agent access to tools. POST the tool’s attach endpoint with target_id=<agent_uuid>. The agent’s enabled_tools list is recomputed on every invocation, so attaching/detaching takes effect on the next agent run. The target must be an element listed in the tool’s contract.yaml attaches list (typically agents).

attachments

Get /ops/attachments | Auth: Read

List all modifiers and resources attached to this element

Returns both modifiers (policy enforcement) and resources (data injection) with is_modifier flag to distinguish. Items in the generated MODIFIER_TYPES list are modifiers; everything else is a resource. Includes cascade_policy and version pin info.

batch_stats

Get /ops/batch_stats | Auth: Read

Get per-element statistics for all children of this element

Returns per-child stats plus an aggregate. Most meaningful on compound or manifest form elements (repositories, circles, projects); atoms have no children so the result is an empty children array with a zeroed aggregate. Uses efficient GROUP BY SQL. Weighted averages for eval scores.

click

Post /ops/click | Auth: Write

Click an element by CSS selector

Clicks an element in the user’s real browser via content script injection. Optional url parameter targets a specific tab; defaults to active tab. Returns success, tag name, and text.

compose

Post /ops/compose | Auth: Execute

Batch add and remove modifiers on this element in a single call

Declarative composition: add modifiers by ref path (slug or path@version) and remove by attachment ID, all in one atomic call on the target element. Each ‘add’ entry resolves the source element, validates topology, attaches with optional priority and cascade policy. Each ‘remove’ entry deletes the attachment row. Returns a summary of what was added and removed. Example: compose({ add: [{ref: “my-prompt”}, {ref: “rate-limit/api@v2”, priority: 50}], remove: [{attachment_id: “uuid”}] })

content

Post /ops/content | Auth: Read

Get the HTML content of the current page

Gets HTML content from the user’s real browser tab. Returns the full page HTML including dynamically-rendered content. No navigation occurs.

context

Get /ops/context | Auth: Read

Get connected elements (graph traversal)

Graph traversal showing all connected elements with their relationship type (contains, contained_by, references, referenced_by, attaches, etc.). Use ?depth=N to control traversal depth (default 1) and ?types=actor,data to filter by element types.

cookies

Post /ops/cookies | Auth: Read

Get cookies for a domain from the connected browser

Reads cookies for a domain from the user’s real browser, including HttpOnly cookies that JavaScript cannot access. First checks the in-memory cookie jar (synced via cookie_delta messages). If stale, requests fresh cookies from the extension (5s timeout). The domain parameter must be a domain name (e.g., “example.com”), not a full URL.

create

Post /ops/create | Auth: Write

Create child element

POST to the parent path — element_type goes in the request body, NOT the URL. Both element_type and slug are required and must be non-empty. Name is derived from slug if omitted. Writes to both Git and PostgreSQL. All elements are stored flat under the circle — no intermediate library wrapper rows.

delete

Delete /ops/delete | Auth: Admin

Delete element (soft delete)

Soft delete — sets state to ‘deleted’ but retains the record. Cannot delete elements that have children (has_no_bond precondition) or active runs. Requires admin auth and confirmation.

detach

Post /ops/detach | Auth: Read

Detach this tool from a target agent element

Removes tool access from the agent. Takes effect on next agent invocation. Requires the same target_id used in attach.

disable

Post /ops/disable | Auth: Admin

Disable element (hides and prevents use)

Idempotent — safe to call on already-disabled elements. Optionally pass a reason string. Disabled elements cannot be invoked or executed. Inverse of enable.

enable

Post /ops/enable | Auth: Admin

Enable element (makes usable and visible)

Idempotent — safe to call on already-enabled elements. Transitions element to ready/enabled state. Cannot enable deleted elements. Inverse of disable.

export_bundle

Get /ops/export/bundle | Auth: Read

Export element as downloadable git bundle

On non-root-namespace elements, returns a binary git bundle. On root-namespace (circle) elements, dispatch hands off to the circle’s own export_bundle op, which returns a multi-element JSON envelope with one base64 bundle per child element — this is intentional, not an error.

fetch

Post /ops/fetch | Auth: Write

Execute an HTTP request using the browser’s session and cookies

The most powerful user-browser operation. Executes an HTTP request inside the user’s real browser context with credentials:include by default — inherits all cookies, auth headers, and session state. 30s timeout. Supports any HTTP method, custom headers, and request body. Use this to call authenticated APIs that would reject server-side requests. Returns full response (status, headers, body).

get

Get /ops/get | Auth: Read

Get element details

Element is already resolved by the routing layer — this returns the cached element, not a fresh DB query. Use the path /api/{circle}/{slug} to address elements.

import_bundle

Post /ops/import/bundle | Auth: Write

Import git bundle into element

Accepts a base64-encoded git bundle in the JSON bundle_base64 field. Use overwrite=true to replace existing elements with same slug (default skips duplicates). Imported elements get new UUIDs. Returns counts of imported/skipped elements and any errors.

intention

Get /ops/intention | Auth: Read

Get element intention with full inheritance chain

Returns three levels: direct (this element’s intention), inherited (from category and root), and resolved (final merged intention). Useful for understanding an element’s purpose in context of its hierarchy.

invoke

Post /ops/invoke | Auth: Execute

Invoke the tool with input

Tools are primarily invoked indirectly by agents (the agent loop calls tools automatically). Direct invoke is for standalone testing. Input must match the tool’s port schema. Use ?async=true to get a run_id for polling. Browser tools return screenshots as base64 PNG.

list_attachments

Get /ops/targets | Auth: Read

List all agents this tool is attached to

Returns all agent elements where this tool is currently attached. Shows target_id, target_type, priority, and cascade_policy.

logs

Get /ops/logs | Auth: Read

Get execution logs

mcp_tool_def

Get /ops/mcp/tool | Auth: Read

Get this tool’s MCP tool definition (name, description, inputSchema)

navigate

Post /ops/navigate | Auth: Write

Navigate to a URL in the connected browser

Sends a navigate command to the user’s real browser via the extension WebSocket bridge. The extension navigates the active tab (or specified tab). Returns url, title, and screenshot. Requires the Triform Connect extension to be connected (state: connected).

promote

Post /ops/promote | Auth: Admin

Promote element configuration to a target environment

Only for manifest-form elements (projects). Environments advance: dev → demo → live. dev→demo requires member+ role, demo→live requires admin. Freezes member versions at promotion time (creates snapshot). Persists environment config to spec.environments.

readme

Get /ops/readme | Auth: Read

Get element README.md content

Reads README.md from the element’s git repository. Returns empty content (not an error) if no README exists. Always returns markdown format.

readme_update

Post /ops/readme_update | Auth: Write

Update element README.md content

Creates or overwrites README.md in the element’s git repo. Commits to the draft branch. Content must be provided as a markdown string.

remove-modifier

Post /ops/remove-modifier | Auth: Execute

Remove an attached modifier from this element by attachment ID

Removes a modifier/resource attachment by its row ID. The ID comes from the attachments or context API. This is the reverse of attach — called on the target element, not the source.

reset

Post /ops/reset | Auth: Execute

Reset tool state to idle

Use when a tool is stuck in error state. Resets to idle so it can be invoked again. For browser tools, this also clears the CDP session — the next navigation starts fresh.

restore

Post /ops/restore | Auth: Admin

Restore element to a specific version

Automatically snapshots the current state before restoring (creates a ‘Before restore to vN’ version entry). Writes restored spec to git as .triform/spec.yaml. Git failures warn but don’t fail the operation — DB state is authoritative. Cannot restore deleted elements.

run_get

Get /ops/runs/{run_id} | Auth: Read

Get details of a specific run

runs

Get /ops/runs | Auth: Read

List execution runs

schema

Get /ops/schema | Auth: Read

Get input/output port schemas (MCP tools/list compatible)

Returns the MCP-compatible tool schema. Useful for validating what inputs a tool expects before invoking. For platform tools, the schema reflects currently enabled capabilities.

screenshot

Post /ops/screenshot | Auth: Read

Take a screenshot of a tab in the connected browser

Captures a screenshot of the visible area of a tab in the user’s browser. Returns base64-encoded PNG data URL with width/height. Optional url targets a specific tab.

source

Get /ops/source | Auth: Read

Get any file’s content from the element’s git repository

Reads an arbitrary file from the element’s CAS-backed git tree by its relative path. Same store as readme, just generalized. Path safety: rejects .. traversal, leading /, and null bytes. Use this to view main.py for action elements, asset files for SPAs, etc. Returns empty content (not an error) if the file doesn’t exist.

source_branches

Get /ops/source/branches | Auth: Read

List Source branches for this element

Returns the standard draft/demo/live Source branches, their current commits, and promotion relationships. Use GET /api/{element_path}/ops/source/branches.

source_promote

Post /ops/source/promote | Auth: Write

Promote Source branch forward

Promotes draft to demo or demo to live through the generated element op path. Direct Git pushes to demo/live are blocked by Source policy.

source_repair

Post /ops/source/repair | Auth: Write

Inspect or repair the element Source index

Runs Source repair through the element operation path. Defaults to dry_run=true; set dry_run=false only after reviewing a dry-run report.

source_status

Get /ops/source/status | Auth: Read

Get Source control status for this element

Returns the branch-aware clone URL, checkout commands, current draft commit, child source-link count, portable export summary, Source health, warnings, and auth hints for the addressed element. Use the element-first path: GET /api/{element_path}/ops/source/status.

source_validate

Post /ops/source/validate | Auth: Read

Validate Source branch contents

Validates a Source branch before accepting local Git workflow changes or promotion. Defaults to branch=draft and rejects runtime data, generated output, secret material, and unreadable CAS refs.

stats

Get /ops/stats | Auth: Read

Get aggregate statistics for this element

Health status is computed: error if errors_per_day > 5 or success_rate < 0.8, warning if errors_per_day > 0 or success_rate < 0.95. Firing alerts escalate health to error/warning. Default period is ‘day’. Returns runs_per_day, success_rate, avg_duration_ms, and more.

storage

Post /ops/storage | Auth: Read

Get localStorage and sessionStorage for an origin

Reads localStorage and sessionStorage from the user’s browser for a specific origin. The origin must be a full origin URL (e.g., “https://example.com”), not just a domain. Requires an open tab on that origin.

tree

Get /ops/tree | Auth: Read

Get the element’s position in the graph — ancestors, children, references, and subtree statistics

Uses per-circle ElementGraph cache for O(1) lookups. Returns ancestors (containment chain), children (direct), members (references), referenced_by (reverse refs), attachments, and subtree stats. Default depth is 3, max is 10. Pass ?include_metadata=true for name/state on each node.

type_text

Post /ops/type | Auth: Write

Type text into an element by CSS selector

Types text into an input element in the user’s real browser via content script. Both selector and text are required. Optional url targets a specific tab.

update

Patch /ops/update | Auth: Write

Update element

Partial update — send only the fields you want to change. spec, name, and intention are all independently optional. spec MUST be a JSON object when present; deep-merged into the existing spec by default. Empty {"spec":{}} preserves existing spec content but still records a new version (no-op for content, not for version state). To clear/replace the entire spec wholesale send {"spec":{...},"deep":false}. List-typed spec fields use replace semantics (the patch list replaces the existing list, no array merging). Coordinates Git + DB writes. Slug cannot be changed after creation.

update_meta

Patch /ops/update_meta | Auth: Write

Update element metadata (lightweight merge — does NOT bump version or snapshot spec)

Shallow JSONB merge into element.meta. Top-level keys in the provided value replace existing meta values; other keys are preserved. Used for UI metadata like canvas positions, panel state, viewer preferences. Wire-shape op_name is update_meta (distinct from update) so SSE subscribers + the cache auto-invalidator can distinguish lightweight metadata changes from spec edits without inspecting the payload. The MutatingElementStore wrapper stamps this op_name on the lifecycle event emitted by update_element_meta storage calls.

version

Get /ops/version | Auth: Read

Get current version or full history

Returns current version by default. Pass ?history=true for full version history (up to ?limit=N, default 50). Versions are backed by the element_versions table. Every spec update creates a new version entry.

Error Codes

Code	Class	Retryable	Description
BROWSER_NOT_CONNECTED	conflict	yes	No browser extension is currently connected for this circle
BROWSER_TIMEOUT	timeout	yes	Operation timed out waiting for browser response
BROWSER_FETCH_FAILED	internal	yes	Browser fetch request failed
BROWSER_NO_MATCHING_TAB	not_found	no	No open tab matches the requested origin