Triformer (triformer)

Category: agents | Form: | Symbol: Tf

Composable AI agent with tools from attached elements

AI agent that gets its capabilities from attached elements — it has no built-in tools. Attach a platform element to grant tools (workspace, shell, git, web, devtools). Attach prompt elements to inject reusable system prompts (merged by priority). Use the “generate” operation for single-turn tasks, “chat” for conversations. Common mistake: invoking a triformer with no platform element attached — it won’t be able to do anything useful. For coding tasks needing a real terminal, use coder instead.

Guide

Composable AI triformer with tools from attached elements

What It Does

Triformer is a composable AI actor that starts with zero built-in capabilities. Every tool the triformer can use comes from attaching tool elements to it — file-read, shell, web-search, git-ops, delegation, and others. This design means any triformer’s exact capabilities are explicit and auditable from its project. Triformers run in an isolated VM, stream events to the frontend, and maintain conversation history across sessions.

Element Definition

Property	Value
Type	triformer
Category	agents
Form	atom
Symbol	smart_toy / #8B5CF6

Properties

Field	Type	Default	Description
brain	string	claude-opus	Brain slug or alias. Use versionless aliases such as claude-opus, claude-sonnet, or claude-haiku; the brain seed resolves the current provider model.
system_prompt	string	—	System prompt for the triformer
max_turns	integer	30	Maximum LLM turns per invocation (1–100)
max_tokens	integer	8192	Maximum tokens per LLM response
temperature	number	0.7	LLM sampling temperature (0–2)
top_p	number	—	Nucleus sampling threshold (0–1). Leave unset for provider default
timeout_ms	integer	180000	Maximum execution time in milliseconds
permissions.read_globs	array	["**/*"]	Glob patterns for allowed read paths
permissions.write_globs	array	["**/*"]	Glob patterns for allowed write paths
permissions.allow_create	boolean	true	Allow creating new files
permissions.allow_delete	boolean	false	Allow deleting files
builder_mode	boolean	false	Enable Triform platform devtools (element CRUD, git, etc.)
context.max_context_files	integer	50	Maximum files to include in context window
enable_retro	boolean	false	Enable session retrospective after completion

Ports

Direction	Port	Type	Required	Description
Input	request	request	Yes	Prompt or messages, optional session ID and context
Output	task	request	Yes	Triformer task result with status, message, and tool results

Topology

• Lives in: agents/triformer/ repository
• Referenced by: apps
• Accepts modifiers: rate-limit, auth-policy, api-token, filter-words, evaluator, platform, browser, user-browser, python, javascript, ruby, rust-fn, go-fn, csharp, hitl, prompt, variable
• Uses resources: brain, sql, document, vector, graph, timeseries

Capabilities

Capability	Description
streaming	Supports SSE event streaming
vm-isolation	Executes in isolated VM
persistence	Conversation persistence across sessions
composable-tools	Tools come from attached elements, not built-in

Error Codes

Code	Class	Retryable	Description
TRIFORMER_NO_TOOLS	validation	No	No tool elements attached — triformer has no capabilities
TRIFORMER_EXECUTION_FAILED	internal	Yes	Triformer execution failed
TRIFORMER_TIMEOUT	timeout	Yes	Triformer exceeded maximum execution time

Quick Start

Creating via API

Create a triformer inside a project, then attach the tools you need:

POST /api/{circle}/{project}/
Content-Type: application/json

{
  "element_type": "triformer",
  "slug": "research-agent",
  "name": "Research Agent",
  "spec": {
    "brain": "claude-opus",
    "system_prompt": "You are a research assistant. Search the web and summarize findings clearly.",
    "max_turns": 20
  }
}

Attach a web search tool:

POST /api/{circle}/{project}/web-search-tool/ops/attach

{ "target_id": "<research-agent-uuid>" }

Basic Usage

Invoke the triformer with a task:

POST /api/{circle}/{project}/research-agent/ops/invoke
Content-Type: application/json

{
  "prompt": "Find the latest benchmarks for Rust async runtimes and summarize the top 3."
}

Project Patterns

How Triformer Fits Into Projects

Triformer is the composable alternative to Coder. Where Coder has a rich set of built-in coding tools, Triformer starts empty and gains capabilities only through explicit attachment. This makes it ideal when you need precise control over what an AI can do: a support agent that can only read a knowledge base, a data agent that can only query a specific database, or an orchestrator that can only spawn delegations.

In development stage, triformers run with the latest attached tool definitions. In demo and live stages, they execute from snapshots to ensure consistent behavior.

Example Project Spec

# A support agent that can search docs and answer questions
elements:
  - element_type: triformer
    slug: support-agent
    spec:
      brain: claude-opus
      system_prompt: |
        You are a customer support agent for Acme Corp.
        Search the knowledge base to answer questions accurately.
        If you cannot find an answer, say so clearly.
      max_turns: 10
      temperature: 0.3

After creating, attach the tools this triformer is allowed to use:

# Attach web-fetch so triformer can read specific documentation pages
POST /api/{circle}/{project}/docs-fetch/ops/attach
{ "target_id": "<support-agent-uuid>" }

# Attach user-interaction so triformer can ask clarifying questions
POST /api/{circle}/{project}/hitl-tool/ops/attach
{ "target_id": "<support-agent-uuid>" }

Common Patterns

Minimal Read-Only Research Agent

A triformer with only web-search and web-fetch attached cannot modify anything, making it safe to expose to untrusted inputs:

POST /api/{circle}/{project}/

{
  "element_type": "triformer",
  "slug": "safe-researcher",
  "spec": {
    "brain": "claude-haiku",
    "system_prompt": "Research the topic and return a structured summary.",
    "max_turns": 15,
    "permissions": {
      "write_globs": [],
      "allow_create": false,
      "allow_delete": false
    }
  }
}

Delegation Orchestrator

A triformer with delegation attached can spawn sub-agents to handle parallel workstreams:

POST /api/{circle}/{project}/

{
  "element_type": "triformer",
  "slug": "orchestrator",
  "spec": {
    "brain": "claude-opus",
    "system_prompt": "Break down complex tasks and delegate sub-tasks to specialized agents.",
    "max_turns": 50
  }
}

Then invoke with a complex task:

POST /api/{circle}/{project}/orchestrator/ops/invoke

{
  "prompt": "Analyze the Q4 sales data, identify the top 5 trends, and draft an executive summary.",
  "context": {
    "available_agents": ["data-analyst", "writer"]
  }
}

Attaching Resources

Resources are data elements injected as environment variables into the triformer’s execution context:

POST /api/{circle}/{project}/{resource-slug}/ops/attach
Content-Type: application/json

{ "target_id": "<triformer-element-uuid>" }

Resource	Environment variable	Use inside triformer
sql	RESOURCE_SQL_{NAME}	Query the database via attached shell or code tools
vector	RESOURCE_VECTOR_{NAME}	Semantic document search
files	RESOURCE_FILES_{NAME}	Object storage read/write
git	RESOURCE_GIT_{NAME}	Repository access

Applying Modifiers

Modifier	Use case
file-read	Let the triformer read files in its workspace
file-write	Let the triformer write files in its workspace
shell	Let the triformer run shell commands
web-search	Let the triformer search the web
web-fetch	Let the triformer fetch specific URLs
git-ops	Let the triformer perform git operations
browser	Let the triformer control a headless browser
delegation	Let the triformer spawn sub-agent tasks
user-interaction	Let the triformer ask the user clarifying questions
evaluator	Auto-evaluate triformer output before completing
api-token	Grant access to Triform platform devtools (for builder_mode)

Common Mistakes

Invoking a triformer with no tools attached. A triformer with no tool modifiers attached returns TRIFORMER_NO_TOOLS immediately. At minimum attach one tool element before invoking.

Confusing tool elements with resource elements. Tool elements go in attaches: (they give the triformer capabilities). Data resource elements go in uses: (they provide env vars). Attaching a sql element gives the triformer a connection string in its environment — but the triformer still needs a shell or code-search tool modifier to actually use it.

Triformer is the universal AI actor. Triformer is the composable AI element — attach tool elements to give it capabilities. For code execution, attach shell and file-write tool elements. For browsing, attach browser. The triformer’s capabilities are entirely defined by its attached tools.

Workflows

setup-agent

Set up an AI agent with tools and start using it

1. Attach platform tools - Grants workspace, shell, git, web, and devtools capabilities triform_element(action: "create", element_type: "platform", name: "{slug}-tools")
2. Choose a brain - Set spec.brain to any model available in your circle’s labs triform_ops(action: "call", slug: "{slug}", operation: "update", input: { spec: { brain: "claude-opus" } })
3. Add a system prompt - Attach prompt elements to inject reusable instructions (merged by priority) triform_element(action: "create", element_type: "prompt", name: "{slug}-prompt")
4. Start chatting - The agent is ready — start a conversation triform_ops(action: "call", slug: "{slug}", operation: "chat", input: { message: "Hello" })

data-pipeline-agent

Build an agent that processes data from attached sources

1. Create a data source - Create a SQL, document, or vector element triform_element(action: "create", element_type: "sql", name: "pipeline-db")
2. Attach platform tools triform_element(action: "create", element_type: "platform", name: "{slug}-tools")
3. Set brain and system prompt triform_ops(action: "call", slug: "{slug}", operation: "update", input: { spec: { brain: "claude-opus", system_prompt: "You are a data analyst..." } })
4. Chat with data context triform_ops(action: "call", slug: "{slug}", operation: "chat", input: { message: "Analyze the data in the attached database" })

State Guidance

State	Guidance	Next actions
draft	Agent is in draft. Attach a platform tool and a brain before transitioning to ready.	Attach platform tools: triform_element(action: "create", element_type: "platform", name: "{slug}-tools") Set brain: triform_ops(action: "call", slug: "{slug}", operation: "update", input: { spec: { brain: "claude-opus" } })
error	Agent encountered an error. Check logs and reset to ready.	Reset to ready: triform_ops(action: "call", slug: "{slug}", operation: "lifecycle", input: { target_state: "ready" })
ready	Agent is ready. Start a conversation or run a single-turn task.	Chat: triform_ops(action: "call", slug: "{slug}", operation: "chat", input: { message: "Hello" }) Generate: triform_ops(action: "call", slug: "{slug}", operation: "generate", input: { prompt: "..." })
running	Agent is currently executing. Wait for completion or check status.

Authoring Hints

Field	Help	Example
brain	Brain (model). The conscious brain — main LLM for conversations and tool use. Pick any model available in your circle’s labs.	claude-opus
max_tokens	Max tokens. Maximum tokens per response. Model-dependent upper bound. Default 8192.	``
max_turns	Max turns. Maximum LLM request/response cycles per invocation. Default 30.	``
subconscious.enabled	Subconscious enabled. Master switch for all subconscious facets (memory, knowledge, emotions).	``
subconscious_brain	Subconscious brain. Default brain for all subconscious facets (knowledge, memory, emotions). Should be fast and cheap.	``
system_prompt	System prompt. Instructions defining the agent’s personality and behavior. Stored as system-prompt.md in workspace.	You are a helpful assistant...
temperature	Temperature. Sampling temperature: 0 = deterministic, 2 = maximum creativity. Leave unset for model default.	``

Error Recovery

Error	Recovery guidance	Next actions
auth	Brain authentication failed. The lab’s API key may be missing or expired.	Check lab configuration: triform_element(action: "list", element_type: "lab")
brain_not_found	The specified brain was not found. Check that the model exists in an accessible lab.	List available brains: triform_element(action: "list", element_type: "brain") Use default brain: triform_ops(action: "call", slug: "{slug}", operation: "update", input: { spec: { brain: "claude-opus" } })
no_tools	Agent has no tools attached. Without a platform element, the agent cannot perform any actions.	Attach platform tools: triform_element(action: "create", element_type: "platform", name: "{slug}-tools")
timeout	Agent execution timed out. The task may be too complex for the configured turn limit.	Increase max turns: triform_ops(action: "call", slug: "{slug}", operation: "update", input: { spec: { max_turns: 60 } }) Increase timeout: triform_ops(action: "call", slug: "{slug}", operation: "update", input: { spec: { timeout_ms: 300000 } })

Relationships

• Attaches to: rate-limit, auth-policy, api-token, filter-words, evaluator, platform, chromeless, user-browser, python, javascript, ruby, rust-fn, go-fn, csharp, hitl, prompt, variable
• Uses: brain, sql, document, vector, graph, timeseries

Capabilities

• companion: Can serve as an interactive companion in the workspace
• conversational: Supports conversation sessions with message history
• streaming: Supports SSE event streaming
• vm-isolation: Executes in isolated VM
• persistence: Conversation persistence across sessions
• composable-tools: Tools come from attached elements, not built-in
• public-access: Can serve conversations to unauthenticated guest visitors
• awareness: Receives contextual signals from UI and other elements

Properties

Property	Type	Default	Description
brain	string	""	The main LLM for conversations, reasoning, and tool use.
mouth	string	""	Mouth element (TTS voice bank) this agent speaks through. Leave empty to use the circle default.
mouth_config	object	{}	Mouth-specific configuration — the sub-form is rendered by the AgentVoiceConfigurator based on the selected mouth’s voice_mode. Typical shapes: cloning → { “voice_id”: “” } preset → { “preset”: “alloy” } instruction → { “instruction”: “warm British narrator…” } Cleared automatically when mouth is unset.
ears	string	""	Ears element (STT transcriber) this agent hears through. Leave empty for the circle default.
max_turns	integer	30	Maximum LLM turns per invocation. Each turn is one request/response cycle.
timeout_ms	integer	180000	Maximum execution time in milliseconds (1s to 1h)
coordinator	boolean	false	Whether this agent acts as a team coordinator (loads 9-section coordinator system prompt and task delegation tools)
enable_retro	boolean	false	Enable session retrospective after completion
enable_thinking	boolean	false	Enable extended/chain-of-thought reasoning. Default OFF for snappy chat. When true: Claude/MiniMax-M2 get a thinking budget (max_tokens/2, capped at 10240); GLM/Kimi keep their provider-default thinking behaviour. When false: explicitly disabled on GLM/Kimi via thinking: {type: disabled}. Phone path always disables regardless (12-17s silence is unacceptable on a call).
max_tokens	integer	8192	Maximum tokens per LLM response. Model-dependent upper bound.
temperature	number	1.0	LLM sampling temperature. 0 = deterministic, 2 = maximum creativity.
top_p	number	—	Nucleus sampling threshold.
system_prompt	string	""	System prompt for the agent. Overridden by attached prompt elements.
permissions	object	—	Controls which files the triformer can read and write within its workspace
subconscious_brain	string	—	Default brain for all subconscious facets. Individual brains in subconscious_brains can override this.
subconscious_brains	array	—	N independent subconscious brains — each with its own model, capabilities, and activation rules. When present, the flat brain pickers (subconscious_brain, knowledge_brain, etc.) and the subconscious object are used as fallback only.
subconscious	object	—	The agent’s subconscious — parallel processes that run alongside the conscious stream. Each facet operates independently using a fast brain. Configure via ‘Show raw data’ for advanced facet tuning.
awareness	object	—	Configure which contextual signals this triformer responds to. Signals are emitted by UI components and other elements, routed to the triformer’s subconscious or conscious mind.
paused	boolean	false	Set by pause op. While true, the agent’s tool-call loop defers new LLM requests. Cleared by resume op.
pause_reason	string	""	Free-text reason recorded when the agent was paused. Consumed by HITL and driver-signal.
paused_at	string	""	RFC3339 timestamp of the most recent pause transition. Empty when not paused.
public_access	object	—	Pre-authentication guest access. Managed at the platform level, not per-agent.

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).

answer_question

Post /ops/answer_question | Auth: Execute

Deliver an answer to a pending HITL question from this triformer

Resolve a pending HITL question from the triformer. Requires question_id and answer string. The agent loop blocks on a oneshot channel until this is called. Questions appear in agent events with type ask_question.

attach

Post /ops/attach | Auth: Read

Attach this actor to a target element

Call this ON the modifier/resource element, passing target_id of the actor. The target’s contract.yaml must declare the modifier kind in attaches: or uses:. Priority controls evaluation order for modifiers (lower = first).

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.

cancel_delegation

Post /ops/cancel_delegation | Auth: Execute

Cancel a delegated task (A2A-aligned, idempotent)

Cancel a pending or running delegation. Idempotent — cancelling an already-terminal delegation is a no-op.

chat

Post /ops/chat | Auth: Execute

OpenAI-compatible chat completion using the triformer’s model and system prompt

OpenAI-compatible chat endpoint. Send messages array with role/content pairs. Supports multi-turn conversation with full message history. Use this for chat-style interactions; use generate for task-oriented single-turn execution.

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”}] })

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.

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.

delegate

Post /ops/delegate | Auth: Execute

Delegate a task to another actor element (fire-and-forget)

Dispatch a task to another agent element. Requires target (element path or slug) and prompt. The delegation is circle-scoped and A2A-aligned. Returns delegation_id for status tracking. Target must be an agent-type element in the same circle.

delegation_status

Post /ops/delegation_status | Auth: Execute

Check the status of a delegated task

Check status of a delegated task. Requires delegation_id. Terminal states (completed, failed, cancelled) are immutable.

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 actor from a target element

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.

generate

Post /ops/generate | Auth: Execute

Run the triformer with a prompt

Main entry point for single-turn execution. Requires prompt field. Returns generation_id for tracking. Model defaults to claude-opus. Tools are resolved from attached modifiers at session start. Events stream via NATS on circle.{circle_id}.agent.{element_id}.{generation_id} channel. Use session_id to group related generations.

generation_get

Get /ops/generations/{generation_id} | Auth: Read

Get a specific generation with full output

Get full details of a specific generation including prompt, response, tool calls, token usage, and duration. Requires generation_id in input.

generations

Get /ops/generations | Auth: Read

List triformer generation history

Lists generation history with pagination. Filter by ?session_id to see all generations in a conversation. Returns generation_id, status, model, created_at for each entry.

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.

get_attached_modifiers

Get /ops/attached | Auth: Read

Get elements that are attached to this actor

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 actor with input

Always include data:{} even for no-input actors. Use ?stream=true for streaming output (agents support this). Use ?async=true to get a run_id immediately and poll via run_get. Input must match the actor’s port schema (check via schema operation). Creates a run record in execution history.

list_attachments

Get /ops/targets | Auth: Read

List all elements this agent is attached to

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

logs

Get /ops/logs | Auth: Read

Get execution logs

memories

Get /ops/memories | Auth: Read

List the triformer’s subconscious memories

Lists durable memories stored by the triformer’s subconscious system. Memories are automatically created, updated, and deleted by the subconscious evaluator — they cannot be consciously edited by the triformer. Filter by category (fact, preference, procedure, context, correction) or search by content.

memory_delete

Post /ops/memory_delete | Auth: Write

Delete a specific memory

Permanently remove a memory from the triformer’s subconscious. This is an administrative action — the triformer itself never consciously manages memories.

memory_get

Get /ops/memories/{memory_id} | Auth: Read

Get a specific memory with metadata

pause

Post /ops/pause | Auth: Execute

Suspend the triformer’s tool-call loop; state persists across restart

Pauses the triformer at the next turn boundary. The agent loop polls spec.paused each turn; while paused, no new LLM requests are submitted. Any in-flight tool call completes; pause is observed at the next turn. Safe to call when no run is active — it just sets persistent state. Optional reason is a short free-text hint consumed by HITL and driver-signal. Idempotent: calling pause on an already-paused triformer refreshes reason and paused_at.

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.

refine

Post /ops/refine | Auth: Execute

Iteratively refine a previous generation with feedback

Continue from a previous generation. Requires generation_id (from a prior generate) and prompt. Appends to the existing conversation context. Useful for iterative refinement without losing prior tool call history.

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.

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.

resume

Post /ops/resume | Auth: Execute

Clear the triformer’s paused state

Resumes a paused triformer. Does not restart a stopped run — it only clears the pause flag so the next turn (or the next generate/chat call) proceeds normally. Idempotent: resuming a non-paused triformer is a no-op and returns paused=false.

revert_to_turn

Post /ops/revert_to_turn | Auth: Execute

Revert the workspace to the state captured at a specific turn

Roll back conversation to a specific turn number, discarding subsequent turns. Useful for correcting agent mistakes without starting over.

run_cancel

Post /ops/runs/{run_id}/cancel | Auth: Execute

Cancel a running execution

Only works on runs with status pending or running. Already-completed or failed runs cannot be cancelled. The run transitions to cancelled state and triggers run.cancelled event.

run_get

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

Get details of a specific run

runs

Get /ops/runs | Auth: Read

List execution runs

Filter with ?status=completed|failed|running, paginate with ?limit=N&offset=N. Default limit is 50. Returns total count for pagination.

schema

Get /ops/schema | Auth: Read

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

Call this before invoking an actor to discover its expected input/output format. Returns MCP-compatible tool definitions — useful for building dynamic tool UIs or A2A integration.

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.

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.

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
TRIFORMER_NO_TOOLS	validation	no	No tool elements attached — triformer has no capabilities
TRIFORMER_EXECUTION_FAILED	internal	yes	Triformer execution failed
TRIFORMER_TIMEOUT	timeout	yes	Triformer exceeded maximum execution time