From 3bd76990af728312bbc01e5204b3b40c1411d544 Mon Sep 17 00:00:00 2001 From: Blocks Task Runner Date: Thu, 1 Oct 2026 22:49:54 +0000 Subject: [PATCH 1/2] Fix inaccuracies found during end-to-end validation on dev - 401/403: a malformed Authorization header returns 403, not 401 - Tool-call payload: args are top-level keys, not nested under "input" - Note that outcomes live in the transcript, not the pre-implementation plan - Step 2 reuses the session response from step 1 instead of refetching - Typo in description: "working with the Blocks" -> "working with Blocks" Co-Authored-By: Claude Fable 5.1 --- skills/blocks-api/SKILL.md | 6 +++--- skills/blocks-api/references/sessions-get-overview.md | 9 +++++---- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/skills/blocks-api/SKILL.md b/skills/blocks-api/SKILL.md index bb222f2..c360424 100644 --- a/skills/blocks-api/SKILL.md +++ b/skills/blocks-api/SKILL.md @@ -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 @@ -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 | diff --git a/skills/blocks-api/references/sessions-get-overview.md b/skills/blocks-api/references/sessions-get-overview.md index b659ae3..7360dae 100644 --- a/skills/blocks-api/references/sessions-get-overview.md +++ b/skills/blocks-api/references/sessions-get-overview.md @@ -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" > session.json ``` Useful fields: `title`, `pull_requests`, `source_url`, `is_archived`, @@ -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 ``` @@ -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__": "", "input": ""}`. Invocation only, no result. + `message` is a JSON string `{"__name__": "", ...tool-specific args}`. Invocation only, no result. - **Outcomes only:** `?type=final_message` gives one completed reply per thread. - **One thread:** `?thread_id=` or `/sessions/{id}/threads/{thread_id}/messages`. From d1ce684e08f21812b7c86f04d674dea7f779f1bd Mon Sep 17 00:00:00 2001 From: Blocks Task Runner Date: Thu, 1 Oct 2026 22:58:54 +0000 Subject: [PATCH 2/2] Print the session response in step 1 instead of only saving it Co-Authored-By: Claude Fable 5.1 --- skills/blocks-api/references/sessions-get-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/skills/blocks-api/references/sessions-get-overview.md b/skills/blocks-api/references/sessions-get-overview.md index 7360dae..a8ef53d 100644 --- a/skills/blocks-api/references/sessions-get-overview.md +++ b/skills/blocks-api/references/sessions-get-overview.md @@ -13,7 +13,7 @@ Do these in order and stop as soon as you have enough: ## 1. Fetch a session ```bash -curl -s "$BASE_URL/rest/v1/sessions/$SESSION_ID" -H "$AUTH" > session.json +curl -s "$BASE_URL/rest/v1/sessions/$SESSION_ID" -H "$AUTH" | tee session.json ``` Useful fields: `title`, `pull_requests`, `source_url`, `is_archived`,