blob-reading

name	blob-reading
version	1.0.0
description	Safe resolution of ci-blob:// URIs — extract specific fields without dumping full payloads
license	MIT

Blob Reading

ci-blob:// URIs appear in graph query results when a payload is too large to inline. This skill covers safe resolution patterns to extract only the data you need.

---

When to Use blob_read

Use blob_read only when you need a specific payload from a graph node. Most Cypher queries return structured metadata that is sufficient without resolving any blobs.

Do resolve a blob when:

• You need the full input or output of a specific tool call
• You need the content of a specific assistant turn
• You need a specific field that is stored as a blob URI

Do NOT resolve a blob when:

• You are counting events, listing sessions, or summarizing metadata
• The graph query already returned the structured fields you need
• You are doing broad exploration — scan metadata first, resolve only if required

Most queries don't need blobs. Always exhaust what the graph returns before resolving.

---

How to Resolve a Blob

Follow these four steps to safely resolve a ci-blob:// URI:

Step 1 — Identify the URI Locate the ci-blob:// URI in the graph query result. It will appear as a string value in a node property.

Step 2 — Call blob_read Pass the full URI to the blob_read tool:

blob_read(uri="ci-blob://session_id/key")

Step 3 — Get the file path back blob_read returns {"path": "...", "source": {"name", "url", "origin"}} on success — a local file path where the blob content has been written, plus the endpoint that answered (origin is source, destination, or env). The file is temporary and exists only for this session. ALWAYS state which source a blob was fetched from when reporting.

On failure, source is present only when an endpoint was actually chosen: endpoint-level errors (connection_error, timeout, http_status, decode_error, http_error, and input-validation errors like a missing/invalid uri that occur after selection) carry error.source — cite it. Selection/config errors before any endpoint is chosen (ambiguous_source_selection, unknown_source, source_misconfigured, configuration_error) have no source; report that selection failed rather than inventing one. Call blob_read with list_sources: true to see the connectable set before selecting one by name.

Step 4 — Read selectively Use jq, head, or targeted shell commands to extract only the field(s) you need. Never read the full file into context.

---

Safe Extraction Patterns

Always check size before reading, then extract only the field you need.

In the examples below, $BLOB_PATH stands for the exact path string returned by blob_read — use that returned value verbatim. Never hand-construct or guess a blob path: the blob store lives under the OS temp directory, which differs by platform (/tmp/ci-blobs/... on macOS and Linux, %TEMP%\ci-blobs\... on Windows). The returned path is the only correct source.

Check size before reading:

ls -lh "$BLOB_PATH"
wc -c "$BLOB_PATH"

Extract a top-level field:

jq '.field_name' "$BLOB_PATH"

Check available keys (safe exploration):

jq 'keys' "$BLOB_PATH"

Extract a nested field:

jq '.response.content[0].text' "$BLOB_PATH"

Extract with a size guard (first 500 chars):

jq -r '.response.content[0].text' "$BLOB_PATH" | head -c 500

---

Critical Rules

1. Never dump the full blob — do not cat or read_file the entire blob path into context. A single blob can contain 100k+ tokens.

2. Always check the ci-blob:// prefix — only strings that start with ci-blob:// are blob URIs. Do not pass other strings to blob_read.

3. Prefer targeted extraction — use jq '.specific_field' rather than reading the whole structure.

4. Always check size first — run ls -lh or wc -c on the file path before extracting content. If the file is very large, be even more selective.

5. File path is temporary — the path returned by blob_read is a temporary file for this session only. Do not persist or reference it across sessions.

---

Blob Field Detection

Blob URIs appear as string values in graph node properties. They look like this in raw JSON:

{
  "event_id": "evt_abc123",
  "type": "tool_result",
  "data": "ci-blob://session_abc/tool_result_payload_xyz"
}

To detect and resolve:

1. Parse the node result as JSON first
2. Check if the data field (or whichever field is relevant) starts with ci-blob://
3. Only then call blob_read on that URI

Not every data field contains a blob. Small payloads are inlined as plain JSON — only large payloads are stored as ci-blob:// URIs. Always check the prefix before calling blob_read.