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@rocketride

Run it inside Claude Code after adding the marketplace with /plugin marketplace add rocketride-org/rocketride-server.

Contents

Discovered from source

Skills 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:

NeedLayerPreferred (MCP tool)Fallback (bundled shim, uses SDK)Offline
List/select nodesL1list_components (names/summaries only — wire from the bundled index)tools/generate-index.pybundled LAYER1_NODE_INDEX.json
One node's config schemaL2describe_component../rocketride-configuring-pipelines/tools/fetch-node-schema.py <node>.rocketride/schema/<node>.json
Validate the whole pipelineL3validate_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 → monitorSDK use() → send/chat → get_task_status—
Understand a node/SDK/concept in depthdocsWebFetch one /path.mdtools/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 carries ok: check it; a successful tool call with ok: false is a failure. Where the MCP tools aren't wired, the bundled shims in each sub-skill's tools/ call the real SDK (get_services/get_service/validate/use) and work today. --static mode validates with no engine connection (a fast pre-flight lint). The rrext_get_nodes resource is dead — never use it; discovery is list_components/get_services. A known node missing from live list_components usually means its integration isn't configured — check list_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

  1. Load capabilities — read the node index (L1) directly from its bundled path (../rocketride-designing-pipelines/LAYER1_NODE_INDEX.json, or .rocketride/services-catalog.json in a project). Do NOT find/ls/search for it, and do NOT run generate-index.py — you already know the path; discovery just burns turns. This is the menu of every node you may use: each entry is name · 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.json older than 14 days, surfaced by validate-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 with tools/generate-index.py.
  2. 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.
  3. Configure + validate — REQUIRED SUB-SKILL: rocketride-configuring-pipelines. Per node: fetch schema → fill required fields → run the anti-pattern checklist as a gate → then validate() 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).
  4. 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.
  5. 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

ThoughtReality
"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 chains
  • tools/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:

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

  2. State what the schema says before filling: the required fields, any conditional rules in prose ("if batch_size set, max_batch_wait_ms is required"), and the profile shape for LLM/embedding/store nodes. (Forcing function 10.)

  3. 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_integrations reports per-integration readiness and (with a name) 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_*}), no profile wrapper, and max_tokens is not a real field (the schema calls it modelTotalTokens). Fetch the schema, then copy the <Good> shape — never type config from memory.

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

  1. Assemble the .pipe: components first (each with id, provider, config, and input for non-source nodes; control on controlled nodes), then a literal-GUID project_id, viewport, version: 1. File extension .pipe.
  2. validate() the whole pipeline (L3): validate_pipeline tool / tools/validate-pipeline.py <file> (calls client.validate() → {errors, warnings}) / --static lint if no engine.
  3. The re-validation loop (Forcing function 11): if errors is 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 until errors == []. Never write "validation passed" without a clean result in hand. Address warnings or explain why each is acceptable.
  4. 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

ThoughtReality
"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 table
  • tools/fetch-node-schema.py — get_service(name) (live) or read .rocketride/schema/<name>.json
  • tools/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. Never llms-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

  1. Read the status. MCP: monitor(task_token) → quote state_label, errors[], warnings[], counts verbatim. SDK: get_task_status(token) → state, errors[], warnings[], exitCode, exitMessage, failedCount. Don't paraphrase error messages.
  2. Read the trace. MCP — the run-log (DVR) tools work for past and live runs, keyed by the projectId + source returned by run_pipeline/run_dropper_pipe (never the task token): log_chapters to find the run → log_read for paged events (≤200/page; follow the cursor) → log_traces to list per-object traces → log_trace for one object's full per-node enter/leave with lane, data, result, error. Retention: 7 days dev / 30 days deploy. A run started with pipelineTraceLevel="none" has chapters/console but empty traces — re-run with "summary"/"full" for flow evidence. SDK fallback: the apaevt_flow / _trace events 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.
  3. 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 in rocketride-running-pipelines.
    • Data — empty/garbage input, wrong response key (KeyError) → check input + result_types.
  4. Propose a specific fix tied to the evidence: "Node llm_1 failed: 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 and validate() 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 → misspelled provider; check the index.
  • input has unknown lane (validate) → lane mismatch; add a converter or pick compatible nodes.
  • KeyError: '<key>' → response key vs laneName mismatch; read result_types.
  • Pipeline is already running (task <id>) ... → use_existing=True or terminate() first; a second instance of the same pipe needs its own unguessable tk_ token (SDK use() or rocketride start --token; not MCP).
  • Invalid API key / a project_id rejection → config fix.

Red flags

ThoughtReality
"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). Never llms-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)

  1. Restate the task in one line: the input data, the wanted output. ("Input: user questions. Output: answers grounded in uploaded PDFs.")
  2. Explore archetypes exhaustively. Group the index by classType and 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.
  3. Select, citing each: Found in index: <name> · classType=[…] · lanes={…}. A pipeline needs a resolvable source (one Source-mode node, or several with source naming 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.
  4. 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.

  1. 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; never ls/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.
  2. 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 of from must 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 ingests documents that already carry embedding vectors, and text is not one of its lanes.
    • <Good>: parse_1 → preprocessor_langchain_1 (lane: text), then preprocessor_langchain_1 → embedding_1 (lane: documents), then embedding_1 → store_1 (lane: documents).
  3. 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 their llm/tool/memory via the control plane (the controlled node carries control: [{classType, from: <agent>}], the agent does not) and must meet each invoke min/max from the index.
  4. 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

ThoughtReality
"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 rules
  • examples/ — worked pipelines (simple-chat-rag, document-ingestion, agentic-chat) in examples/README.md + a FAILURE_SCENARIOS.md of 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.md for lanes). Never llms-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.

  1. Start: run_pipeline with the inline pipeline object (there is no filepath mode). One-shot text input? Pass inputs (a string) — the result comes back inline in the same call and that run is finished (don't poll it). Otherwise you get {task_token, projectId, source}. Keep projectId + source — they key the run-log tools if debugging is needed. Reuse a long-lived pipeline with use_existing: true (avoids "Pipeline is already running"); to force a fresh start, terminate then re-run. Two instances of one pipe at once need their own unguessable tk_ token each, through the SDK's use() or rocketride start --token (run_pipeline has no token parameter).
  2. Push input — pick the tool by the source node:
    • Raw text/data → send_data (input is a string — serialize JSON). Result inline.
    • Files from the host → start with run_dropper_pipe instead: it returns an upload_url (multipart-POST the files to it) and a dropper_url (browser drag-drop page to hand the user). send_files reads paths on the engine host and exists only on a local (loopback-bound) engine.
    • chat source → no MCP chat tool exists; use the SDK fallback below.
  3. Poll longer/async runs with monitor (a bounded server-side poll — pass timeout). Quote the snapshot each round: state_label, terminal, counts, errors. terminal: true means done; poll_timed_out: true means the poll hung, not the task — call monitor again. Never one-shot poll and walk away. (Forcing function 12.)
  4. Report the real result. Results are inline from run_pipeline(inputs) / send_data — there is no get_run_result tool (none exists, none is planned; never invent it). Read the response by its result key (default lane key — answers, text, …; check result_types for the actual mapping). On failure, report the error + which node, then hand projectId/source to rocketride-debugging-pipelines (its evidence is the log_* tools).
  5. Clean up — terminate any 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)

  1. Start: result = await client.use(filepath="x.pipe") → token = result["token"] (use_existing=True to reuse; terminate(token) then use() to force fresh).
  2. Push input: chat source → 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 (a PIPELINE_RESULT) — no separate get_result().
  3. 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.
  4. Report as in step 4 above. 5. Clean up — await client.disconnect() (or async 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_add then deploy_to_team (manage later with deploy_list/deploy_status/deploy_set_schedule/ deploy_disable/deploy_remove). Saving / publishing is billable / public — treat like an irreversible action (Waiting = STOP).

Red flags

ThoughtReality
"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). Never llms-full.txt.

MCP servers 1

Sponsors

Details

Marketplace
rocketride-org/rocketride-server
Source
docs/agents
Category
Community