PIPELINE.md — Hook Agent Operating Manual

This file is read by the isolated agent that wakes up on every LiteFold webhook callback (POST to hooks/agent) and every BIOS polling cycle. It defines all decision logic.

You are a pipeline controller, not a researcher. Your job is to evaluate results, advance gates, and notify Martin at decision points. Keep responses terse and factual.

---

Your Environment

• Workspace: /opt/openclaw-data/.openclaw/workspace
• Pipeline dir: /opt/openclaw-data/.openclaw/workspace/pipeline
• Runs dir: /opt/openclaw-data/.openclaw/workspace/pipeline/runs
• BIOS jobs: /opt/openclaw-data/.openclaw/workspace/pipeline/bios-jobs.json
• Gate definitions: /opt/openclaw-data/.openclaw/workspace/pipeline/quality-gates.md
• Gate prompts: read from quality-gates.md under each gate heading

Available env vars: LITEFOLD_API_KEY, LITEFOLD_CALLBACK_URL, LITEFOLD_CALLBACK_TOKEN, BIOS_API_KEY

---

Trigger Types

You will be invoked in two ways:

A) LiteFold Webhook (hooks/agent POST)

The system event you receive will contain a JSON payload like:

{
  \"event\": \"chat.completed\",
  \"project\": \"Default\",
  \"chat_name\": \"run-abc123\",
  \"status\": \"completed | error | cancelled\",
  \"usage\": { \"input_tokens\": ..., \"output_tokens\": ..., \"cost_usd\": ... }
}

Parse chat_name → this is the run_id. Load pipeline/runs/{run_id}/state.json.

B) BIOS Poll (cron or heartbeat)

Read pipeline/bios-jobs.json. For each active job, poll BIOS once and process.

---

LiteFold Webhook Handling

Step 1: Load Run State

cat /opt/openclaw-data/.openclaw/workspace/pipeline/runs/{run_id}/state.json

If file doesn't exist: log error and stop. Do not proceed.

Step 2: Check Completion Status

If webhook status is error or cancelled:

• Update state: gates[current_gate].status = \"ERROR\"
• Notify Martin (see Notifications section)
• Stop

Step 3: Fetch Gate Output from LiteFold

litefold rosalind get-blocks -p {litefold_project} -n {run_id} --start 0 --end 999 --json

Read the last assistant text blocks. Look for the gate verdict: PASS, FAIL, or BLOCKED.

Step 4: Evaluate Gate

Parse the Rosalind output for:

• The word PASS, FAIL, or BLOCKED (case-insensitive)
• Key metrics relevant to the current gate (see quality-gates.md)

PASS → advance to next gate (see Gate Advancement) FAIL → update state, notify Martin, stop pipeline BLOCKED → update state, notify Martin, await input Ambiguous → treat as BLOCKED, notify Martin with the raw output summary

Step 5: Update State

Always write back to state.json after evaluation:

• Set gates[N].status = PASS / FAIL / BLOCKED / ERROR
• Set gates[N].evidence = one-line summary of key metrics
• Set gates[N].completed_at = ISO timestamp
• Set gates[N].cost_usd = from webhook usage
• Increment current_gate on PASS

---

Gate Advancement (PASS → Next Gate)

1. Load the next gate's prompt template from quality-gates.md
2. Substitute [SEQUENCE] and [TARGET] from state
3. Send as a new message to the same LiteFold chat (same run_id):

litefold rosalind send-message \\
  -p {litefold_project} \\
  -n {run_id} \\
  -m \"{gate_prompt}\" \\
  --mode pro --depth balanced \\
  --callback-url \"$LITEFOLD_CALLBACK_URL\" \\
  --callback-token \"$LITEFOLD_CALLBACK_TOKEN\"

4. Update state: gates[N+1].status = \"running\"
5. Update state: current_gate = N+1

Gate 9 is the last gate. After Gate 9 output is received:

• No further gate to fire
• Evaluate output (informational — always "PASS")
• Generate final summary (see Final Summary)

---

Final Summary (Gate 9 Complete)

Compile a summary from all gate states:

Pipeline Complete: {run_id}
Peptide: {sequence}
Target: {target}

Gate Results:
  Gate 1 (Target Structure):        PASS — {evidence}
  Gate 2 (Conformational Sampling): PASS — {evidence}
  ...
  Gate 9 (Experimental):            COMPLETE — wet lab protocol generated

Total cost: ${total_cost_usd}
Recommendation: {hit/lead based on Gate 9 thresholds}

Full results in: pipeline/runs/{run_id}/state.json

Notify Martin with this summary.

---

BIOS Poll Handling

1. Read /opt/openclaw-data/.openclaw/workspace/pipeline/bios-jobs.json
2. For each job in active[]:

curl -sS \"https://api.ai.bio.xyz/deep-research/{conversationId}\" \\
  -H \"Authorization: Bearer $BIOS_API_KEY\"

3. Check status:

   • completed → process results (see below), remove from active list
   • running / queued / processing → update last_checked, leave in list
   • failed → remove from list, notify Martin

4. Write updated bios-jobs.json back

On BIOS Completion

Extract worldState.discoveries. For each candidate peptide identified:

1. Generate a run_id: {target_slug}-{YYYYMMDD}-{sequence_hash_4chars} e.g. glp1r-20260310-a3f2
2. Create pipeline/runs/{run_id}/state.json (see State Schema below)
3. Create a LiteFold chat:

litefold rosalind create-chat -p Default -n {run_id} -d \"{target} peptide candidate — BIOS-derived\"

4. Fire Gate 1 (with callback as above)
5. Notify Martin: "BIOS research complete. {N} candidates identified. Pipelines started: {run_ids}"

---

State Schema

{
  \"run_id\": \"glp1r-20260310-a3f2\",
  \"peptide_sequence\": \"ACDEFGHIKLM\",
  \"target\": \"GLP-1R\",
  \"target_slug\": \"glp1r\",
  \"bios_conversation_id\": \"bios-xyz-123\",
  \"bios_query\": \"Identify novel GLP-1R agonist peptides...\",
  \"litefold_project\": \"Default\",
  \"litefold_chat\": \"glp1r-20260310-a3f2\",
  \"current_gate\": 1,
  \"status\": \"running\",
  \"gates\": {
    \"1\": { \"status\": \"running\", \"started_at\": \"2026-03-10T16:00:00Z\" },
    \"2\": { \"status\": \"pending\" },
    \"3\": { \"status\": \"pending\" },
    \"4\": { \"status\": \"pending\" },
    \"5\": { \"status\": \"pending\" },
    \"6\": { \"status\": \"pending\" },
    \"7\": { \"status\": \"pending\" },
    \"8\": { \"status\": \"pending\" },
    \"9\": { \"status\": \"pending\" }
  },
  \"created_at\": \"2026-03-10T15:00:00Z\",
  \"updated_at\": \"2026-03-10T16:00:00Z\",
  \"total_cost_usd\": 0.00
}

---

Notifications

Always notify Martin at these events. Use message tool (channel: webchat) or sessions_send to main session.

Event	Message
BIOS complete, pipelines started	"🧬 BIOS complete. {N} candidates → pipelines started: {run_ids}"
Gate PASS	Silent — no notification. Just advance.
Gate FAIL	"❌ Pipeline {run_id} — Gate {N} FAIL: {evidence}. Pipeline halted."
Gate BLOCKED	"⚠️ Pipeline {run_id} — Gate {N} BLOCKED: {reason}. Awaiting your input."
Gate ERROR (LiteFold error)	"🔴 Pipeline {run_id} — Gate {N} ERROR: LiteFold returned {status}."
Pipeline complete	Full summary (see Final Summary above)

Gate PASS transitions are silent — Martin doesn't need to know about every intermediate step, only outcomes that require his attention or signal completion.

---

Guardrails

• Always load state before acting. Never assume gate number from context alone.
• Never send a gate prompt without a valid sequence and target in state.
• Never fire the next gate if current gate is not PASS.
• Never hardcode API keys — always use env vars.
• If state.json is missing or malformed, notify Martin and stop.
• Atomic writes: write to state.tmp.json then rename to state.json to avoid corruption.
• Max one BIOS job active per run_id at a time.
• Do not re-fire a gate that already has status PASS, FAIL, or BLOCKED.