runtara

Use to verify changes to agents, capabilities, integrations, steps, or runtime end-to-end before declaring a task done. Boots the full server stack with embedded WASM runner and separate DBs, then drives the server HTTP API to create, compile, and execute a workflow and assert observable behavior. Unit tests are not sufficient — agent/runtime changes must e2e-verify.

Use when local dev state has drifted into a weird shape — failing migrations, half-applied schema changes, stale cached binaries, suspended instances clogging the system. Wipes the e2e DBs and data dir and gives you a clean slate. Distinct from e2e-verify which assumes a clean env.

Use to set up the right RUST_LOG filters and tail server + environment logs scoped to a specific tenant, instance, or component. Saves the "what's the right log filter again" lookup. Pair with trace-instance when you need both API state and live log output.

Use when a workflow that uses a connection misbehaves — to see stored params (secrets masked), token state, rate-limit history, and which integration it belongs to. Catches stale OAuth tokens and misconfigured connection params before you blame the agent.

Use to get a quick health view of a workflow — its definition, registered versions, recent instances and their statuses, and which connections it touches. The "is this thing healthy / what does it look like right now" view, distinct from trace-instance which drills into one specific run.

Use for the tight inner loop when developing or debugging a single capability — rebuild only the changed crate, recompile a small test workflow that exercises it, register, run, dump output. ~10s feedback vs full e2e-verify. Use e2e-verify for the final pre-commit check; use this while iterating.

Use to debug a specific workflow instance — walks through input envelope, per-step state, step inputs/outputs, errors, and final result. Pulls everything from the runtime API (port 7001), no DB queries. The default skill when "this run did something weird and I need to know why".

Use when creating a new pure-WASM agent module (no external service) under crates/runtara-agents. An agent is a logical grouping of capabilities (e.g. xml, csv, http, crypto). For adding a capability to an existing agent, use add-capability instead. For agents that talk to an external service, use add-integration.

Use when adding a new

Use when adding support for a new external service (Salesforce, Notion, Zendesk, etc.) — i.e. an agent that talks to a third-party API and needs stored credentials. Covers the connection params struct, the HttpConnectionExtractor, and the integration agent file. Includes an advanced section for the rare case of adding a brand-new auth flow to the connection subsystem.

Use when adding a new SQL migration to the server or environment database — schema changes, new tables, indexes, extensions. Migrations are auto-applied by sqlx::migrate! at server startup; there is no manual migrate command.

Use when adding a new DSL step type (Conditional, Split, Filter, While, Log, etc.) to the workflow language. Steps are the building blocks of workflow graphs and appear in the Step Picker UI. Distinct from agents and capabilities — a step is workflow-control machinery, not external logic.

Use after backend changes that affect the OpenAPI surface — new capabilities, new step types, new connection types, new HTTP routes — so the frontend's generated API client and type definitions stay in sync. The Step Picker, Connection UI, and most forms are driven by these generated types.

Use to cut a new release — bumps the workspace version, commits, tags, and pushes. The tag push triggers the release CI workflow which publishes to crates.io. Wraps scripts/release.sh with a pre-flight checklist so a release doesn't ship broken.