toolcraft generated CLIs should expose HTTP error details and verbose flags consistently

[kamilio]

Summary

toolcraft/toolcraft-openapi generated CLIs should make HTTP response details and verbose diagnostics consistently discoverable for API failures.

I hit this while using the generated poe-agent-tools CLI to transfer a bot owner. The server returned a useful JSON error body, and the current local CLI does now summarize it in default output, but the documented/global verbose path is inconsistent: -v before the command is rejected, command help does not list --verbose, and the full response body is only available if the user already knows to place --verbose after the leaf command.

Repro

Repo/tooling:

• generated CLI: <workspace>/poe-agent-tools
• generator/runtime source: <workspace>/poe-code/packages/toolcraft and <workspace>/poe-code/packages/toolcraft-openapi
• installed package versions in poe-agent-tools: toolcraft@0.0.63, toolcraft-openapi@0.0.63

Command:

cd <workspace>/poe-agent-tools
node dist/bin/cli.js bot-actions set-owner <bot-handle> \
  --new-owner-handle <target-owner-handle>

Default output currently includes the useful server detail:

Request:  POST https://www.i.quora.com/api/internal_agent/v1/bots/<bot-handle>/actions/set-owner
Status:   403 Forbidden

Message:  bot creator_uid=<creator-uid> is not in the allow-list for /api/internal_agent
Hint:     Check the configured API credentials and permissions.
Re-run with --verbose to see headers and full body.

The raw HTTP response body is:

{"detail":"bot creator_uid=<creator-uid> is not in the allow-list for /api/internal_agent"}

However, the generated CLI rejects -v when used as a global option before the command:

node dist/bin/cli.js -v bot-actions set-owner <bot-handle> \
  --new-owner-handle <target-owner-handle>

Actual output:

Unknown option "-v".
Run poe-agent-tools --help for usage.

And leaf command help does not show the verbose option:

node dist/bin/cli.js bot-actions set-owner --help

Output only shows:

OPTIONS
  <botHandle>                  botHandle (required)
  --new-owner-handle <value>   Poe handle of the user who should become the bot's owner. (required)

But --verbose does work when placed after the leaf command:

node dist/bin/cli.js bot-actions set-owner <bot-handle> \
  --new-owner-handle <target-owner-handle> \
  --verbose

That prints the full request/response transcript, including:

Response body:
  Detail:  bot creator_uid=<creator-uid> is not in the allow-list for /api/internal_agent

Expected behavior

• Generated CLIs should consistently expose documented global flags, especially -v, --verbose.
• poe-agent-tools -v <group> <command> ... should work if verbose is modeled as global in the generated command schema.
• Leaf command help should show --verbose/-v if the command accepts it.
• The default HTTP error summary should keep showing API detail/message fields, as in the current local output, and should have regression coverage for FastAPI-style { "detail": "..." } responses.

Why this matters

For internal-agent generated tools, many failures are permission/configuration failures where the server body is the actionable part. In this case, 403 Forbidden alone is not enough; the body explains exactly what to fix:

bot creator_uid=<creator-uid> is not in the allow-list for /api/internal_agent

If verbose is hard to discover or unavailable in the documented/global position, users and agents will miss the actionable error and have to reproduce the request manually with fetch/curl.

Likely area

• packages/toolcraft/src/cli.ts: global option registration/help and HTTP error rendering
• packages/toolcraft-openapi/src/generate.ts / generated command wiring: emitted verbose parameter is marked { short: "v", scope: ["cli", "sdk"], global: true }, but root-level parsing/help does not behave like a true global option in the generated CLI.

[kamilio]

Resolved by 0b98a47 (fix: expose toolcraft verbose diagnostics).

Verified locally before close:

• npm test -- packages/toolcraft-openapi/src/runtime.test.ts -- -t "accepts -v as a global verbose flag before generated command paths"
• npm test -- packages/toolcraft/src/cli.test.ts -- -t "suppresses schema fields tagged global from leaf help while listing built-in verbose"
• npm test -- packages/toolcraft/src/cli.test.ts -- -t "renders RFC 7807 problem detail response bodies"

Release monitoring for 0b98a47 is green:

• Release: https://github.com/poe-platform/poe-code/actions/runs/27847623134
• Release toolcraft packages: https://github.com/poe-platform/poe-code/actions/runs/27847623148
• Publish Schemas to GitHub Pages: https://github.com/poe-platform/poe-code/actions/runs/27847623137

[kamilio]

Resolved by 0b98a47 and released from main. Verified GitHub runs are green: Release https://github.com/poe-platform/poe-code/actions/runs/27847623134, Release toolcraft packages https://github.com/poe-platform/poe-code/actions/runs/27847623148, Publish Schemas https://github.com/poe-platform/poe-code/actions/runs/27847623137.