Actions

An action is a capability defined in your Twisp tenant, independently of what invokes it. Its definition says what it does: a handler kind and its config, the schemas of what it accepts and returns, the tools and skills it may use, and the policies that bound what it can touch. How it runs is a separate choice. The same action can run when a record changes, on a schedule, when a client or another action calls it, as a turn of a long-running session, or when an agent outside Twisp asks for it.

Every run of every action is an execution: a durable record of what ran, on what input, under which exact version, with what result, and what it called.

The kinds

An action's kind selects its handler. How it runs depends on what else the definition holds: event or schedule triggers make it run on its own, a tool block makes it callable, and a session gives it durable identity across runs. Every action has at least one trigger, a tool block, kind skill, or kind mcp.

The kinds are not exclusive roles. A tool can also have triggers, so the same program runs for events and for calls. An agent can have triggers and a tool block, so it runs for events and other agents can call it. An agent with a session runs through its session instead; a callable agent has none.

How the pieces compose

Actions are built from one another by name:

• Tools call tools. A tool declares the tools it calls, and each call is a child execution. A call and everything beneath it commits or rolls back as one unit. See Tools.
• Agents use tools and skills. An agent can call only the tools it declares and load only the skills it declares, plus the tools a loaded skill makes available. Its model decides which to use; the definition decides what is possible. See Agents and Skills.
• Models are tools. Twisp ships each model, and every tenant can call one like any tool. A Starlark tool can wrap a model so a judgment and the writes it leads to commit together. See Models.
• MCP servers offer tools to outside agents. A server lists the tools and skills an external agent may use, and each request is an execution of the server, recorded like the work of an agent Twisp runs. See MCP Servers.
• Sessions give actions durable identity. A session ties a stream of events, schedule firings, and calls to one subject, such as one account, with its own input, state, history, and end. An agent with a session works in turns and can remember across them. See Sessions and Memory.

Executions

An execution is the universal record. A matching event, a schedule firing, a client's call or start, a session turn, a nested call, a skill load, and a request to an MCP server each produce one. It records its status, the exact action version, its input, every invocation and its output or error, and its full history. Calls and starts link executions into trees, and lineage walks them, so any piece of work can be followed to everything it caused. See Triggers and Executions.

Because every run is recorded with its input and version, a recorded agent turn or MCP request can be replayed against a changed version, and an agent can run in preview mode, doing everything it would do while committing none of its business writes.

Versions and publication

Every write to an action creates a new version, and the action keeps them all. Writes take effect asynchronously: a new or changed definition is pending until it is published. An event is matched against the version published when it committed; a call names the version it runs, and a start runs the current version unless it names one. Each execution is pinned to the version it ran, so editing an action never changes work already recorded.

References between actions choose how they follow change. A reference with a version always uses exactly that version; one without uses the latest version, resolved when each execution starts, and the execution records the version it used. See Publication status and Versions.

The policy chain

Each action runs as its own principal with its own policies, and every operation a tool or agent performs is checked against a chain of policy lists: the client that started the work, then the MCP server, for a request made through one, then the agent, if one is on the call stack, then each tool from the first call down to the one performing the operation. Every layer must allow the operation, so each layer can only narrow what the layers above it allow. Declaring a tool never grants its caller anything, a tool can do only what its callers can, and an agent's policies bound everything it can reach through any tool. See Policy chain and Authority and Audit.

In this section