
rocketride
RocketRide is the leading AI meta-harness with the only enterprise-grade runtime built on C++. Five skills that take a plain-language request to a validated, running RocketRide pipeline, plus the hosted RocketRide MCP server.
- GitHub stars
- 20K
Install
/plugin install rocketride@rocketrideRun it inside Claude Code after adding the marketplace with /plugin marketplace add rocketride-org/rocketride-server.
Contents
Discovered from sourceSkills 5
Building RocketRide Pipelines
Master workflow: a plain-language request in, a valid, running RocketRide pipeline out. Follow the phases in order. Each phase is owned by a REQUIRED SUB-SKILL. The gates are hard stops — present to the user and wait.
THE IRON LAW OF GATES — WAITING = STOP:
WAITING FOR A HUMAN'S ANSWER MEANS ENDING YOUR TURN.
A dismissed / headless / unanswered gate is a STOP — NEVER an approval. No exceptions.
Real-world impact: this one rule took gate blast-through from 32–45% to 0/24 on Haiku — the cheap model behaves like an expensive one because it holds the protocol, not because it is smart.
Waiting means ENDING YOUR TURN. A dismissed question dialog, an unanswered question, or a non-interactive/headless session is a STOP, never an approval. No exceptions:
- Don't "proceed with the recommended defaults" — a recommendation is not a confirmation.
- Don't treat silence, dismissal, or the absence of a user as consent.
- Don't later write "the user approved this" unless a human actually answered. If nobody can answer, deliver the gate brief as your final message and stop — an unbuilt pipeline costs nothing; an unapproved run wastes the user's money and compute.
Full gate rules, the deterministic gate wording, and the forcing functions live in
GATE_PROTOCOL.md. Read it before your first gate. Multi-turn gate state lives in
.context/GATE_STATE.md (in the current project): write it (Write tool) whenever you present a
gate, and read it FIRST on every re-engagement — a fresh session or a vague "continue" must
re-present an AWAITING gate, never auto-approve. See GATE_PROTOCOL §2.
How reliability works here (read this once)
You do not need to be smart to build a correct pipeline. You need to follow the process and let the tools be the judge:
- Never invent a node. Every node you name must be cited from the node index (Phase 0). If it isn't in the index, it doesn't exist — STOP and tell the user.
- Never invent a config field. Fetch the node's schema before configuring it.
- Never claim "valid" or "ran" without the tool saying so.
validate()is the compiler; the run status/result is the proof. Quote them; don't paraphrase. - Count what you list. Every multi-item list ends with a count line so omissions are visible.
The tool/data layer (three layers + run)
Each step has the same fallback ladder — use the first option your environment supports:
| Need | Layer | Preferred (MCP tool) | Fallback (bundled shim, uses SDK) | Offline |
|---|---|---|---|---|
| List/select nodes | L1 | list_components (names/summaries only — wire from the bundled index) | tools/generate-index.py | bundled LAYER1_NODE_INDEX.json |
| One node's config schema | L2 | describe_component | ../rocketride-configuring-pipelines/tools/fetch-node-schema.py <node> | .rocketride/schema/<node>.json |
| Validate the whole pipeline | L3 | validate_pipeline | ../rocketride-configuring-pipelines/tools/validate-pipeline.py <file> (calls client.validate) | ../rocketride-configuring-pipelines/tools/validate-pipeline.py --static <file> (lint only) |
| Run it | — | run_pipeline → send_data/run_dropper_pipe → monitor | SDK use() → send/chat → get_task_status | — |
| Understand a node/SDK/concept in depth | docs | WebFetch one /path.md | tools/fetch-doc.py "<topic>" (fetches ONE live page) | ROCKETRIDE_DOC_MAP.md (this skill dir) + bundled .rocketride/docs/* |
The exact tool names, inputs, and result shapes are frozen in
../MCP_TOOL_CONTRACT.md— use only names listed there. Every MCP result carriesok: check it; a successful tool call withok: falseis a failure. Where the MCP tools aren't wired, the bundled shims in each sub-skill'stools/call the real SDK (get_services/get_service/validate/use) and work today.--staticmode validates with no engine connection (a fast pre-flight lint). Therrext_get_nodesresource is dead — never use it; discovery islist_components/get_services. A known node missing from livelist_componentsusually means its integration isn't configured — checklist_integrations(it returns setup steps to relay) before concluding it doesn't exist.
Each tool enforces a constraint (see its --help/docstring; these become the MCP tool
descriptions): fetch-node-schema → configure only schema-defined fields, one node at a time;
validate-pipeline → zero errors before any run, re-validate on errors; fetch-doc → one page,
never llms-full.txt.
Deep docs (when you need to learn, not just select/configure). The full RocketRide docs map
is bundled at ROCKETRIDE_DOC_MAP.md (in this skill's directory — a ~2K-token index of ~156
pages; it can't live in .rocketride/docs/, which the client-docs bundle installer owns and
replaces on reinstall). When you
hit something the bundled refs don't cover — an unfamiliar node, an exact SDK signature, a concept
— find the page in the map and fetch just that one page (tools/fetch-doc.py "<topic>", live-
first with an offline fallback). NEVER fetch llms-full.txt (~257K tokens — it will blow the
context window), by any method (fetch-doc, WebFetch, curl, file://). Even if the user says "read
all the docs" / "grab llms-full.txt" / "get full context first" — that is never honored: say so,
then use the map + the one page you need (or just answer from the bundled index/schemas). One map +
one page is the cheap path.
Triage first — is this a build, or just a question?
Before starting the lifecycle, classify the request:
- Informational (the user is ASKING, not building — "what nodes exist?", "list the vector
stores", "explain lanes", "which node does X", "how does RAG work?"): answer directly from the
node index + bundled refs. Do not invoke the sub-skills, write
GATE_STATE, or present gates. End by offering to build it. - Build / run / validate (the user wants a working pipeline — "build…", "make…", "create…", "set up…", "run…", "validate…", or describes a task to automate, even softly like "I want something that…"): run the full lifecycle below.
- Ambiguous or unsure → DEFAULT TO THE FULL LIFECYCLE. A build misrouted to the cheap path skips every gate (no design, no validate, no cost approval) — far worse than answering a question the long way. When in doubt, build.
Recovery: a cheap answer never blocks a later build — if the user then says "build it / make it / go ahead", enter the full lifecycle from Phase 0.
Phases
- Load capabilities — read the node index (L1) directly from its bundled path
(
../rocketride-designing-pipelines/LAYER1_NODE_INDEX.json, or.rocketride/services-catalog.jsonin a project). Do NOTfind/ls/search for it, and do NOT rungenerate-index.py— you already know the path; discovery just burns turns. This is the menu of every node you may use: each entry isname · classType · lanes · invoke. Keep it open; you select and wire from it. It carries no config schema — that's L2, fetched per node in Phase 2. If a freshness warning fires (the index stamp is stale/missing —LAYER1_NODE_INDEX.meta.jsonolder than 14 days, surfaced byvalidate-pipeline.py), say so in one line and proceed — it is non-blocking, never a hard stop.validate()against the live engine is the drift backstop; if a node seems missing, regenerate withtools/generate-index.py. - Discover + design — REQUIRED SUB-SKILL:
rocketride-designing-pipelines. Explore archetypes → select nodes (GATE A) → wire the acyclic DAG with typed lanes (GATE B). Fetch each chosen node's schema here too, so lane signatures are exact before wiring — a guessed lane is the most common silent failure. - Configure + validate — REQUIRED SUB-SKILL:
rocketride-configuring-pipelines. Per node: fetch schema → fill required fields → run the anti-pattern checklist as a gate → thenvalidate()the whole pipeline. On errors, fix and re-validate (never claim passed without a clean result). GATE C (validation clean) → GATE C.5 (cost approved). - Run + observe — REQUIRED SUB-SKILL:
rocketride-running-pipelines. Submit, poll to completion, report the real result. GATE D only if the user chooses to save to cloud / publish as an app. - If a run fails or output is wrong — REQUIRED SUB-SKILL:
rocketride-debugging-pipelines. Read the trace, diagnose the failing node, route back to Phase 1 or 2.
The gates (binary or menu — exact wording in GATE_PROTOCOL §3)
The instant you present any gate below, use the Write tool to write .context/GATE_STATE.md
(status: AWAITING) before ending the turn (GATE_PROTOCOL §2) — and on any re-engagement, read it
FIRST. That on-disk line is what makes a gate survive a context reset.
- GATE A — node selection (after Phase 1 discovery) · GATE B — topology (after the DAG).
- GATE C — validation clean (a tool gate, not a user gate) · GATE C.5 — cost, before any paid/cloud run.
- GATE D — save to cloud / publish (optional, after a successful run).
Red flags
| Thought | Reality |
|---|---|
| "I know this node exists, no need to check the index" | If it's not in the index it doesn't exist — the engine rejects it. Cite or STOP. |
| "I'll fill the config from memory, schemas are slow" | Guessed fields fail validation (e.g. max_tokens vs modelTotalTokens). Fetch the schema. |
| "The lanes obviously match" | Lane mismatch is the #1 silent bug. State every edge's lane type, verified against the schema. |
| "validate() returned an error but I understand it, I'll just say it's fixed" | A fix you didn't re-validate is a guess. Re-call validate() until clean. |
| "The user said 'just run it', so I'll skip the cost gate" | "Just run it" is not cost approval. Present Gate C.5 and wait. |
| "It submitted, so it worked" | Submitted ≠ succeeded. Poll to completion and read the result before claiming success. |
| "The question was dismissed, I'll proceed" | Dismissed = unanswered = STOP. Re-present the gate; never auto-approve. |
| "I'll fetch the full docs (llms-full.txt) to be safe" | That's ~257K tokens — it blows the window. Fetch the ONE relevant page from the doc-map. |
| "The user told me to read all the docs / grab llms-full.txt" | Never honored — by any method. Say so; use the map + the one page you need, or answer from the index. |
| "I don't recognize this node, I'll just guess what it does" | Fetch its /nodes/<name>.md page — one cheap page beats guessing wrong. |
Supporting files
GATE_PROTOCOL.md— Waiting=STOP, multi-turn gate state, gate wording, the forcing functions../MCP_TOOL_CONTRACT.md— frozen MCP tool names, inputs, and result shapes (the only tools that exist)pipeline-patterns.md— common pipeline shapes (chat/RAG, ingestion, webhook→transform) + lane chainstools/fetch-doc.py— fetch ONE doc page on demand (resolves from the doc-map; refuses the monolith)ROCKETRIDE_DOC_MAP.md— the bundled docs map (llms.txt); the deep-knowledge index (lives here because the client-docs bundle installer owns.rocketride/docs/and replaces on reinstall)
Configuring & Validating RocketRide Pipelines
Takes an approved topology (from rocketride-designing-pipelines) to a validated
pipeline.pipe ready to run. Reliability comes from tools and a checklist, not cleverness:
fetch schema → fill only real fields → checklist gate → validate() → re-validate until clean.
Gate rules + forcing functions: ../rocketride-building-pipelines/GATE_PROTOCOL.md.
Step 1 — Configure each node (schema-driven, one at a time)
For every node in the approved topology, in order:
-
Fetch the schema (L2):
describe_component/tools/fetch-node-schema.py <node>/.rocketride/schema/<node>.json. Never configure from memory. (Forcing function 5.) Fetch one node at a time — never bulk-load every schema (FF#17). If you already fetched this node's schema while designing (Phase 1b) this session, reuse it with--cache-ok(serves the cached copy with no reconnect — still schema-grounded, just not re-fetched); a full re-fetch only on a cache miss. -
State what the schema says before filling: the required fields, any conditional rules in prose ("if
batch_sizeset,max_batch_wait_msis required"), and the profile shape for LLM/embedding/store nodes. (Forcing function 10.) -
Fill only fields the schema defines. Use
${ROCKETRIDE_*}env references for secrets — never literal keys. Secret values never travel through tools or the model: over MCP, credentials are configured out-of-band —list_integrationsreports per-integration readiness and (with aname) returns concrete setup steps to relay to the user. LLM/embedding/store nodes use a profile block:"config": { "profile": "openai-5", "openai-5": { "apikey": "${ROCKETRIDE_OPENAI_KEY}" }, "parameters": {} }Source nodes need the full source config, not
{}:{ "hideForm": true, "mode": "Source", "parameters": {}, "type": "<provider>" }.The block above is the
<Good>shape. The<Bad>shape — guessed from memory — fails validation and leaks a key:"config": { "model": "gpt-5", "apikey": "sk-...", "max_tokens": 4096 }Three bugs in one line: a literal key (must be
${ROCKETRIDE_*}), noprofilewrapper, andmax_tokensis not a real field (the schema calls itmodelTotalTokens). Fetch the schema, then copy the<Good>shape — never type config from memory. -
Run the 9-point checklist as a gate (full list in
PIPELINE_ANTIPATTERNS.md). State each item yes/no for this node before moving on — do not skip and claim "applied":Node
<id>: 1 ext✓ 2 components-order✓ 3 literal-guid✓ 4 source-match✓ 5 unique-id✓ 6 input-array✓ 7 lane-types✓ 8 acyclic/no-orphan✓ 9 ROCKETRIDE_ env✓
Step 2 — Assemble & validate (→ Gate C)
- Assemble the
.pipe:componentsfirst (each withid,provider,config, andinputfor non-source nodes;controlon controlled nodes), then a literal-GUIDproject_id,viewport,version: 1. File extension.pipe. - validate() the whole pipeline (L3):
validate_pipelinetool /tools/validate-pipeline.py <file>(callsclient.validate()→{errors, warnings}) /--staticlint if no engine. - The re-validation loop (Forcing function 11): if
errorsis non-empty, show them verbatim, fix the offending node (loop back to Step 1 for that node — don't restart design), then call validate() again. Repeat untilerrors == []. Never write "validation passed" without a clean result in hand. Address warnings or explain why each is acceptable. - Gate C is a tool gate, not a user gate — it is "passed" only when validate() returns zero
errors. Quote it:
validate(): 0 errors, K warnings.
Step 3 — Cost approval (→ Gate C.5)
Before handing off to run, estimate cost and gate it (GATE_PROTOCOL §5):
- Count paid/LLM nodes × expected calls × rough token cost; note if it runs on cloud compute (billed to the wallet) vs the user's own dev keys locally.
- Gate C.5:
This run will cost ≈ $X (). Approve this run? (yes / no) Then Write
.context/GATE_STATE.md=GATE C.5 | presented | status: AWAITING(§2), and STOP and wait. "Just run it" earlier is not cost approval. A tiny local test on the user's own key can be a one-line confirm; cloud/large runs always gate.
Hand the validated .pipe to rocketride-running-pipelines.
Red flags
| Thought | Reality |
|---|---|
| "I'll set apikey/model from what I remember" | Fetch the schema; field names differ per provider (modelTotalTokens, profile keys). |
| "Required fields only; prose constraints are optional" | Conditional rules ("if X then Y") are required too — state and satisfy them. |
| "I'll run the checklist once at the end" | Per node, as a gate, stated yes/no. A checklist skimmed once is a checklist skipped. |
| "validate() erred but I fixed it in the text" | A fix you didn't re-validate is a guess. Re-call validate() until errors == []. |
| "Zero errors but warnings — ship it" | Read each warning; fix or justify. Warnings are often the real bug. |
| "Hardcode the key just for the test" | Never. ${ROCKETRIDE_*} always; literal keys leak and break substitution. |
| "Skip the cost gate, it's a small run" | Present Gate C.5 regardless; let the user decide. |
Supporting files
PIPELINE_ANTIPATTERNS.md— the real common mistakes, the 9-point checklist, the error tabletools/fetch-node-schema.py—get_service(name)(live) or read.rocketride/schema/<name>.jsontools/validate-pipeline.py—client.validate(pipeline);--static= local lint, no engine- deep docs — for provider-specific config nuance/profiles the schema alone doesn't explain,
fetch the node's doc page:
../rocketride-building-pipelines/tools/fetch-doc.py "<node-name>"(→/nodes/<name>.md). The schema gives exact fields; the page gives the why. Neverllms-full.txt.
Debugging RocketRide Pipelines
Diagnose, don't guess. A failed run has a real cause in the status/trace; find it, then route the fix to the right phase. No re-running until the cause is identified and the fix is validated.
Procedure
- Read the status. MCP:
monitor(task_token)→ quotestate_label,errors[],warnings[],countsverbatim. SDK:get_task_status(token)→state,errors[],warnings[],exitCode,exitMessage,failedCount. Don't paraphrase error messages. - Read the trace. MCP — the run-log (DVR) tools work for past and live runs, keyed by the
projectId+sourcereturned byrun_pipeline/run_dropper_pipe(never the task token):log_chaptersto find the run →log_readfor paged events (≤200/page; follow the cursor) →log_tracesto list per-object traces →log_tracefor one object's full per-nodeenter/leavewithlane,data,result,error. Retention: 7 days dev / 30 days deploy. A run started withpipelineTraceLevel="none"has chapters/console but empty traces — re-run with"summary"/"full"for flow evidence. SDK fallback: theapaevt_flow/_traceevents in the response. Either way, find the first node whose op shows an error or whose output is empty/wrong — that's the failure point. Downstream errors are usually consequences. - Classify the cause (see
ERROR_TABLE.md):- Config — bad/missing field, wrong API key, wrong model name → fix in
rocketride-configuring-pipelines(re-fetch schema, re-validate). - Wiring/lane — lane mismatch, missing converter, wrong source method → fix in
rocketride-designing-pipelines(re-wire), then re-configure + re-validate. - Runtime — event-loop blocked (
Connection closed/timeout),Pipeline is already running, blocking I/O → fix the run code inrocketride-running-pipelines. - Data — empty/garbage input, wrong response key (
KeyError) → check input +result_types.
- Config — bad/missing field, wrong API key, wrong model name → fix in
- Propose a specific fix tied to the evidence: "Node
llm_1failed:Invalid API key. The${ROCKETRIDE_OPENAI_KEY}env var is unset / wrong. Fix: set it, re-validate, re-run." Route to the owning phase. Do not re-run until the fix is made andvalidate()is clean again.
Common diagnoses (full table in ERROR_TABLE.md)
Connection closed/Connection closed unexpectedly→ event loop blocked by sync I/O (most common runtime failure) — fix the run code, not the pipeline.The service <provider> was not found→ misspelledprovider; check the index.input has unknown lane(validate) → lane mismatch; add a converter or pick compatible nodes.KeyError: '<key>'→ response key vslaneNamemismatch; readresult_types.Pipeline is already running (task <id>) ...→use_existing=Trueorterminate()first; a second instance of the same pipe needs its own unguessabletk_token (SDKuse()orrocketride start --token; not MCP).Invalid API key/ aproject_idrejection → config fix.
Red flags
| Thought | Reality |
|---|---|
| "I'll just re-run, maybe it works" | Find the cause first; blind re-runs cost money and teach nothing. |
| "The last node errored, fix that node" | The first failing node in the trace is usually the cause; later errors cascade. |
| "Connection dropped — the engine is flaky" | Almost always a blocked event loop (sync I/O in async code), not the engine. |
| "I'll paraphrase the error" | Quote it verbatim — the exact message maps to the exact fix. |
| "Fixed it, re-running" | Re-validate() after any fix before re-running. |
Supporting files
ERROR_TABLE.md— error message → cause → owning phase → fix- deep docs — for failure modes the table doesn't cover, fetch ONE page:
../rocketride-building-pipelines/tools/fetch-doc.py "error handling"(→/concepts/error-handling.md) or… "observability"(→/protocols/websocket/observability.md). Neverllms-full.txt.
Designing RocketRide Pipelines
Turns a plain-language request into an approved, lane-correct DAG — before any node is
configured. Two outputs, two gates: a node selection (Gate A) and a wired topology (Gate B).
The gate rules and forcing functions are in
../rocketride-building-pipelines/GATE_PROTOCOL.md — they apply here.
You work from the node index (L1): LAYER1_NODE_INDEX.json (bundled), or the live
get_services() / .rocketride/services-catalog.json. Each entry is name · classType · lanes · invoke. The index is enough to select and wire; it carries no config fields (that's Phase 2).
The bundled index is reconciled against this repo's node corpus (nodes/src/nodes/), so it can
drift from the set a particular live engine actually has registered.
The live MCP list_components tool lists names/summaries only (no lanes) and hides nodes whose
integration isn't configured — use it to check availability, but wire from the bundled index +
per-node schemas. If a node you expect is missing from it, check list_integrations first.
Phase 1a — Discover (→ Gate A)
- Restate the task in one line: the input data, the wanted output. ("Input: user questions. Output: answers grounded in uploaded PDFs.")
- Explore archetypes exhaustively. Group the index by
classTypeand walk every archetype that could plausibly contribute. Don't stop at the first match. The archetypes:source(chat/webhook/dropper/filesys/telegram) ·data/parse (parse/llamaparse/reducto/ landing_ai_parse/landing_ai_extract) ·text(extract_data/ner/anonymize_text/dictionary/prompt/summarization) ·preprocessor·image·audio·video·embedding·llm(14 providers) ·store(vector DBs) ·database(db_) ·agent·tool(tool_) ·memory·rerank·search·guard·infrastructure/target/response_*(terminals). For each relevant archetype, list the candidate nodes you see in the index. - Select, citing each:
Found in index: <name> · classType=[…] · lanes={…}. A pipeline needs a resolvable source (one Source-mode node, or several withsourcenaming the one that starts the run, in the file or at launch) and a terminal (response_*for a reply; a store /db_*for ingestion). Pull the right converters from the lane cheat-sheet in../rocketride-building-pipelines/pipeline-patterns.md. - Gate A — end with the count line and the gate:
Archetypes explored (N). Selected nodes (M): <name · role>, … — all cited from the index. Approve these M nodes? (yes / adjust / cancel) Then use the Write tool to write
.context/GATE_STATE.md=GATE A | presented | status: AWAITING(GATE_PROTOCOL §2 — so the gate survives a context reset), and STOP. (See §1.)
Phase 1b — Design the DAG (→ Gate B)
Only after Gate A is approved.
- Fetch each selected node's schema (L2 —
describe_component/tools/shim in../rocketride-configuring-pipelines/tools/fetch-node-schema.py/.rocketride/schema/<n>.json). You need the real lane signatures here, not the index summary — wiring from the summary is the most common silent bug. (Forcing function 8.) Lazily — only for the nodes you selected at Gate A; neverls/cat/glob the whole.rocketride/schema/dir or "pull every schema up front" (FF#17). Select from the index first; fetch only the few schemas you need. - Wire the lanes. Each non-source node gets
input: [{lane, from}]. State every edge with its lane type:chat_1 → embedding_1 (lane: questions). The output lane offrommust be a real output of that node and a valid input of the target. If types don't match, insert a converter (cheat-sheet) — don't force it.<Bad>:parse_1 → store_1 (lane: text), wiring parsed text straight into a vector store. It passes the eye test but fails validation: a store ingestsdocumentsthat already carry embedding vectors, andtextis not one of its lanes.<Good>:parse_1 → preprocessor_langchain_1 (lane: text), thenpreprocessor_langchain_1 → embedding_1 (lane: documents), thenembedding_1 → store_1 (lane: documents).
- Apply the structural rules (
PIPELINE_RULES_SUMMARY.md): a resolvable source (rule 1); acyclic (no loops); no orphans (every node reachable from the source); embedding before any store; agents wire theirllm/tool/memoryvia the control plane (the controlled node carriescontrol: [{classType, from: <agent>}], the agent does not) and must meet eachinvokemin/max from the index. - Draw it (Mermaid or ASCII) and Gate B:
. Edges (K): <node → node (lane: type)>, … — all lane-checked against schemas. Approve this topology? (yes / adjust / cancel) Then Write
.context/GATE_STATE.md=GATE B | presented | status: AWAITING(§2), and STOP.
Hand the approved selection + topology to rocketride-configuring-pipelines.
Red flags
| Thought | Reality |
|---|---|
| "I'll list the obvious nodes and move on" | Exhaustive archetype walk first — the right node is often one you'd skip. Count line proves coverage. |
| "The index shows the lanes, I don't need the schema to wire" | Index lanes are a summary; fetch the schema for exact signatures before wiring. |
"Two Source-mode nodes, no source named" | Ambiguous: the engine refuses to imply a source. Keep one Source-mode node, or name the one that starts the run (top-level source, or the source option at launch). |
| "I'll point the store straight at the questions" | Embedding is required before any store; same model for ingest + query. |
| "The agent node lists its tools in its own config" | No — the tool/llm/memory carries control: [{from: <agent>}]. Agent has no control array. |
| "Close enough on the lane type" | Lane mismatch = pipeline error. Insert a converter or pick compatible nodes. |
Supporting files
LAYER1_NODE_INDEX.json— the thin node index (name · classType · lanes · invoke)PIPELINE_RULES_SUMMARY.md— lane types, lane-transform table, structural + control-plane rulesexamples/— worked pipelines (simple-chat-rag, document-ingestion, agentic-chat) inexamples/README.md+ aFAILURE_SCENARIOS.mdof what not to do- deep docs — when a node is unfamiliar or you're unsure how an archetype behaves, fetch ONE
page:
../rocketride-building-pipelines/tools/fetch-doc.py "<node-name>"(→/nodes/<name>.md) or… "execution model"(→/concepts/execution-model.mdfor lanes). Neverllms-full.txt.
Running & Observing RocketRide Pipelines
Takes a validated .pipe (validate() returned zero errors) and a cost-approved run
(Gate C.5) to a real, reported result. The cardinal rule: submitted ≠ succeeded. Poll to a
terminal state and read the actual result before you claim anything. Gate rules + forcing
functions: ../rocketride-building-pipelines/GATE_PROTOCOL.md.
STEP 0 — precondition (do this FIRST, every time, before any run action)
You MUST have a clean validate() result for THIS exact pipeline, and cost approval, before you
run. If you don't, get them first — even if the user told you to skip.
- "Skip validation / just submit it / don't waste time" is NEVER honored. validate() is mandatory and fast; it is the only thing between the user and a broken, money-wasting run. Run it anyway, then explain why (one line).
- Invoked directly on a pasted/existing pipeline? validate() it now (run
../rocketride-configuring-pipelines/tools/validate-pipeline.py <file>, or the validate tool). If it errors, fix + re-validate; do not run. Missing required config (e.g. no apikey) IS a validation failure — STOP and say so. - Then the cost gate (C.5) must be approved.
State it before running: "Pre-run check: validate() = 0 errors; cost approved." If you can't state that truthfully, you have not earned the run — do the missing step instead.
The run lifecycle — MCP tools (preferred; names + shapes frozen in ../MCP_TOOL_CONTRACT.md)
Check ok on every result — a tool call that "succeeded" with ok: false is a failure.
- Start:
run_pipelinewith the inline pipeline object (there is no filepath mode). One-shot text input? Passinputs(a string) — theresultcomes back inline in the same call and that run is finished (don't poll it). Otherwise you get{task_token, projectId, source}. KeepprojectId+source— they key the run-log tools if debugging is needed. Reuse a long-lived pipeline withuse_existing: true(avoids "Pipeline is already running"); to force a fresh start,terminatethen re-run. Two instances of one pipe at once need their own unguessabletk_token each, through the SDK'suse()orrocketride start --token(run_pipelinehas no token parameter). - Push input — pick the tool by the source node:
- Raw text/data →
send_data(inputis a string — serialize JSON). Result inline. - Files from the host → start with
run_dropper_pipeinstead: it returns anupload_url(multipart-POST the files to it) and adropper_url(browser drag-drop page to hand the user).send_filesreads paths on the engine host and exists only on a local (loopback-bound) engine. chatsource → no MCP chat tool exists; use the SDK fallback below.
- Raw text/data →
- Poll longer/async runs with
monitor(a bounded server-side poll — passtimeout). Quote the snapshot each round:state_label,terminal,counts,errors.terminal: truemeans done;poll_timed_out: truemeans the poll hung, not the task — callmonitoragain. Never one-shot poll and walk away. (Forcing function 12.) - Report the real result. Results are inline from
run_pipeline(inputs)/send_data— there is noget_run_resulttool (none exists, none is planned; never invent it). Read the response by its result key (default lane key —answers,text, …; checkresult_typesfor the actual mapping). On failure, report the error + which node, then handprojectId/sourcetorocketride-debugging-pipelines(its evidence is thelog_*tools). - Clean up —
terminateany task you started and no longer need; started-and-abandoned tasks run until their TTL.
SDK fallback (no MCP tools wired, or a chat-source pipeline)
- Start:
result = await client.use(filepath="x.pipe")→token = result["token"](use_existing=Trueto reuse;terminate(token)thenuse()to force fresh). - Push input:
chatsource →await client.chat(token=token, question=q); raw data →await client.send(token, data); files →await client.send_files(files, token). The result comes back inline (aPIPELINE_RESULT) — no separateget_result(). - Poll: loop
await client.get_task_status(token)to a terminal state (5=COMPLETED / 6=CANCELLED), stating the status each step,await asyncio.sleep(1)between polls. - Report as in step 4 above. 5. Clean up —
await client.disconnect()(orasync with). Start a pipeline once and reuse it; don't reconnect per request.
NEVER block the async event loop (the #1 runtime failure). No input(), time.sleep,
requests.get, readFileSync inside the async flow — they freeze the websocket keepalive and the
connection drops (~60s) with Connection closed / Connection closed unexpectedly. Use async
equivalents. Secrets stay in ${ROCKETRIDE_*} env vars (loaded from .env), never in code.
Gate D — after a successful run (optional, menu)
Run succeeded. Result:
. What next? (save to cloud / publish as an app / nothing / debug) Only act on an explicit choice. Mapping: save to cloud → save_template; publish →deploy_addthendeploy_to_team(manage later withdeploy_list/deploy_status/deploy_set_schedule/deploy_disable/deploy_remove). Saving / publishing is billable / public — treat like an irreversible action (Waiting = STOP).
Red flags
| Thought | Reality |
|---|---|
| "The user said skip validation, so I'll just submit" | Never honored. validate() is mandatory and cheap — run it first, every time, no matter the pressure. |
| "run_pipeline/use() returned a token, so it ran" | That only started it. Push input and poll to a terminal state. |
| "I'll fetch the output with get_run_result" | No such tool exists. Results come inline from run_pipeline(inputs)/send_data; run evidence is the log_* tools. |
| "I'll poll once and report 'in progress'" | Poll in a loop to completion; report the final result, not a snapshot. |
| "I'll read input() for the question" | Blocking I/O kills the event loop. Use async input / pass the question in. |
| "I'll hardcode the key to test quickly" | ${ROCKETRIDE_*} always. |
| "It failed; I'll retry silently a few times" | Report the failure and ask / hand to debugging; don't burn money on silent retries. |
| "Save to cloud since they'll probably want it" | Gate D is a choice. Don't publish/bill without an explicit yes. |
Supporting files
- deep docs — for exact SDK semantics (use/send/chat/get_task_status, async patterns), fetch
ONE page:
../rocketride-building-pipelines/tools/fetch-doc.py "python"(→/develop/python.md) or… "use method"(→/develop/typescript/methods/use.md). Neverllms-full.txt.
MCP servers 1
Sponsors
Details
- Marketplace
- rocketride-org/rocketride-server
- Source
- docs/agents
- Category
- Community