Skip to content

Fix inaccuracies found during end-to-end validation on dev #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
AlejandroEsquivel merged 2 commits into from
Oct 1, 2026
Merged

Fix inaccuracies found during end-to-end validation on dev #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3bd7699
Fix inaccuracies found during end-to-end validation on dev
AlejandroEsquivel Oct 1, 2026
d1ce684
Print the session response in step 1 instead of only saving it
AlejandroEsquivel Oct 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions skills/blocks-api/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
name: blocks-api
description: >
Use when working with the `Blocks` to inspect existing agent sessions:
Use when working with `Blocks` to inspect existing agent sessions:
fetch a session by ID, read its transcript (user prompts and assistant replies),
and drill into tool calls when more detail is needed. Trigger on "Blocks session",
"Blocks API", "fetch blocks session transcript" or any request to read what a
Expand Down Expand Up @@ -34,7 +34,7 @@ Read the file for the task at hand. Each one is a complete, ordered walkthrough.

| Status | Meaning |
| --- | --- |
| 401 | Missing or malformed `Authorization` header |
| 403 | Bad key, or key for a different environment |
| 401 | Missing `Authorization` header |
| 403 | Malformed header (e.g. `Bearer`), bad key, or key for a different environment |
| 404 | Session not in your workspace, or artifact not attached to it |
| 422 | Bad `limit`, `page`, `type`, `role`, `direction`, non-UUID id, comma lists |
9 changes: 5 additions & 4 deletions skills/blocks-api/references/sessions-get-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,13 +6,14 @@ Do these in order and stop as soon as you have enough:

1. Fetch the session for metadata and `plan_artifact_ids`.
2. If there is a plan, read it first. It holds most of the useful information.
3. Read the transcript overview (one call).
3. Read the transcript overview (one call). The plan is written before
implementation, so what actually happened (fixes, PRs, outcomes) lives here.
4. Pull tool calls only if you still need to know how something was done.

## 1. Fetch a session

```bash
curl "$BASE_URL/rest/v1/sessions/$SESSION_ID" -H "$AUTH"
curl -s "$BASE_URL/rest/v1/sessions/$SESSION_ID" -H "$AUTH" | tee session.json
```

Useful fields: `title`, `pull_requests`, `source_url`, `is_archived`,
Expand All @@ -25,7 +26,7 @@ Useful fields: `title`, `pull_requests`, `source_url`, `is_archived`,
at that plan's latest version, oldest plan first. Take the last entry.

```bash
PLAN_ARTIFACT_ID=$(curl -s "$BASE_URL/rest/v1/sessions/$SESSION_ID" -H "$AUTH" | jq -r '.plan_artifact_ids[-1]')
PLAN_ARTIFACT_ID=$(jq -r '.plan_artifact_ids[-1]' session.json)
PLAN_URL=$(curl -s "$BASE_URL/rest/v1/sessions/$SESSION_ID/artifacts/$PLAN_ARTIFACT_ID" -H "$AUTH" | jq -r '.url')
curl -s "$PLAN_URL" # presigned, valid 6 days, NO Authorization header
```
Expand Down Expand Up @@ -56,7 +57,7 @@ make two calls, `?type=message&role=user` and `?type=message`, merge by `ts`.
## 4. More detail, only when needed

- **Tool calls:** add `type=tool_call`, e.g. `?type=message&type=tool_call&role=user&role=assistant`.
`message` is a JSON string `{"__name__": "<tool>", "input": "<args>"}`. Invocation only, no result.
`message` is a JSON string `{"__name__": "<tool>", ...tool-specific args}`. Invocation only, no result.
- **Outcomes only:** `?type=final_message` gives one completed reply per thread.
- **One thread:** `?thread_id=<id>` or `/sessions/{id}/threads/{thread_id}/messages`.

Expand Down
Loading