Recipes
This page is a worked example, not a specification. It narrates one real debugging session to show a concrete failure mode and the change that closed it. The reference pages describe behavior; this one shows it in context.
The pattern under test: an upstream API that returns a binary payload where a wrapper assumes JSON, and what an agent does to work around the gap.
Background
The f fj uck
existed before any of this. It wraps the
@llamaduck/forgejo-ts
SDK — all 491 generated REST endpoints, exposed by name
(f fj call repoGet ownerName=… repoName=…) or by raw path
(f fj GET /repos/o/r). The base URL comes from the git origin of the
directory you run in, and the token comes from
f creds under the instance's host name. Inside any
clone, f fj … just works:
f creds set forgejo.example.com <pat> # once, per instance
f fj whoami # inside a clone
What it could not do was read Actions logs, and the SDK is why: the
generated operations include listActionRuns and actionRun, but the
spec has no log endpoint at all — and the one raw endpoint that exists,
GET …/actions/runs/{id}/logs, returns a zip (one file per job), not
text. A JSON-printing wrapper meets a binary payload, and the log is
gone. So the uck's own ls help text said it plainly:
some operations are absent from the spec — Actions LOGS are: call the raw path instead
"Call the raw path instead" is where the LLM landed, every time.
The "before" — the LLM's workarounds
1. Guessing which of three numbers was the run id. The API, the tasks endpoint, and the web UI each carry a different identifier for one run:
f fj call listActionRuns ownerName=myorg repoName=myrepo limit=5
# rows carry .id — 3767
f fj call listActionTasks …
# rows carry .id — 4491 (a per-attempt row id)
# and .run_number — 10 (what the web UI URL /actions/runs/10 shows)
Feed the wrong one to /actions/runs/{id} and the API answers with a bare
"resource does not exist" — no status code, no hint. The agent burned a
round-trip concluding it had a permissions problem before realizing it
had used the run_number from the URL it was staring at.
2. The zip arriving as garbled text. The JSON printer mangled the binary on the way out:
f fj GET /repos/myorg/myrepo/actions/runs/3767/logs > /tmp/logs.bin
# PK..-J-...[binary re-encoded as text]
So the workaround was a Python subprocess that captured raw bytes around
f fj, wrote them to a file, and unzipped — a scratch script kept in
/tmp just to see a CI log:
import subprocess, zipfile
raw = subprocess.run(
["f", "fj", "GET", "/repos/myorg/myrepo/actions/runs/3767/logs"],
capture_output=True,
).stdout
open("/tmp/logs.zip", "wb").write(raw)
for n in zipfile.ZipFile("/tmp/logs.zip"):
print(n, len(n.read()))
Even that corrupted on some runs, because the uck's stdout path was text.
3. Paging 10,000-line logs blind. No grep across jobs, no job filter —
sed -n ranges and hope, repeated until the --- FAIL: line surfaced.
Each window was a full tool round-trip with the context re-sent.
The session's own notes from that era:
binary corruption:
f fj GET …/logsreturns a binary zip thatf fjprints as garbled text; piping corrupts it. Workaround: python3 subprocess.run(..., capture_output=True).
The fix — two words added to an existing uck
The gap was small enough that the right response was not a new tool but a
small edit to the uck that already owned Forgejo auth, base-URL
resolution, and error reporting. That is the contract paying off:
f fj is a directory with an index.js
(the uck contract), so extending it means editing a file —
no new package, no new config, no deployment. The change landed in the
fj bucket and was
published with f uck push fj:
f fj runs [newest|<run_id>]— list recent runs as<id> status event sha ref duration, or show one run plus its jobs. The list comes from the samelistActionRunsdata the agent used to parse by hand, but the API's id is what gets printed, so the three-id confusion disappears by construction.f fj joblogs <run_id> [grep] [--job x] [--out dir]— the raw logs endpoint, handled as bytes: a ~30-line ZIP central-directory reader (stored +zlib.inflateRawSyncfor deflated entries — the SDK's client already fetched witharraybuffer, so no new dependencies) unzips the run's log, then greps every job withfile:line:contentor saves the files to a directory.
How easy the edit actually was, in the uck's own terms: the run-listing
and job-listing calls reuse the uck's existing makeClient/token
plumbing verbatim; the only genuinely new code is the zip walk and the
output format. Everything the LLM had to solve around the uck —
authentication, which instance, error messages that say what is wrong —
was already solved inside it.
One follow-up commit the same day:
runs tolerates a truncated consumer (| head -3) instead of dying with
an EPIPE stack — the kind of edge a two-hour session immediately
exercises.
The "after" — the same session
Which run, and did it break:
f fj runs newest
3774 success pull_request fec3afa9 #1291 9m
3773 failure pull_request 58eb1186 #1291
3772 success pull_request 8fefc8e0 #1267 10m
3771 failure pull_request eb3c213d #1267 9m
Which job, and what failed:
f fj runs 3767
job 4491 failure build · lint · test · e2e
job 4492 success tui-integration
3767 failure pull_request 831fff27 #1267 9m
f fj joblogs 3767 "--- FAIL"
build · lint · test · e2e-4491-attempt-1.log:9348:--- FAIL: TestListWebhooks (6.68s)
One command: the zip is downloaded as bytes, unzipped, grepped across every job. The job name is in the filename, so the agent never opens a log viewer to learn which of five jobs blew up. Narrow to one job:
f fj joblogs 3767 "go test|TUITest" --job tui
tui-integration-4501-attempt-1.log:711:ok github.com/nucleotide/tui/app 5.559s
Whole log for deeper reading ("x" matches nothing — you only want
the files):
f fj joblogs 3772 "x" --out /tmp/logs3772
saved build · lint · test · e2e-4500-attempt-1.log -> /tmp/logs3772/build · lint · test · e2e-4500-attempt-1.log
saved tui-integration-4501-attempt-1.log -> /tmp/logs3772/tui-integration-4501-attempt-1.log
Now the profiling pass is a plain one-liner over text, and the answer comes out in one round-trip:
gap 29s after: Run `npm audit` for details.
gap 90s after: > Task :checkKotlinGradlePluginConfigurationErrors SKIPPED
gap 90s after: Preparing "Install Android SDK Build-Tools 34 v.34.0.0".
gap 78s after: ok github.com/nucleotide/tui/app 165.077s
Cold Gradle daemon (~2 min), Go tests running per-package (queue alone:
243 s), and a Playwright Chromium download every run (~75 s). That
attribution became the follow-up PR that cut the pipeline.
Is the fix in yet:
f fj runs newest && f fj joblogs 3774 "--- FAIL"
# silence means green
What changed, concretely
| Before (LLM + the REST-only fj uck) | After (f fj runs / joblogs) |
|---|---|
Python subprocess wrapping f fj to capture zip bytes; corrupted when the text path kicked in |
joblogs treats the response as binary end to end |
Unzip + grep via scratch scripts in /tmp |
joblogs <run> <grep> [--job x] [--out dir] |
Three candidate run ids, guessed; opaque resource does not exist |
runs prints the API's id; the UI's number is never involved |
sed -n paging over 10k-line logs, one round-trip per window |
grep across all jobs in one call |
| ~6–8 tool round-trips to answer "what failed" | 2 |
Good to know
- Auth — same as the rest of
f fj:--token,FORGEJO_TOKEN, or thecredsuck keyed by host. Read access to the repo is enough for runs and logs (owner-only endpoints like runners and secrets still 403). - Repo —
runs/joblogsdefault to the git origin of the current directory;--repo owner/namepoints elsewhere. - Extending it further — the words live in
kensand-fcli-ucks
under
fj/; it is oneindex.js. If your instance's Actions surface differs, edit the file andf uck push fj.