chore: harness port override + error envelope + SSE path docs (closes #38 #39 #40)#46
Merged
Merged
Conversation
…#38) The `cli-doctor` row shells out to `hal0 doctor --plain`, whose port-collision preflight defaults to 8080 + 3001 — the canonical prod install ports. On a host with a co-resident prod hal0 install, the dev-install harness's doctor row would (correctly) flag the collision and `fail`, poisoning the harness exit code. Set `HAL0_DOCTOR_PORTS="${HAL0_DOCTOR_PORTS:-18080 13001}"` near the top of cli-test.sh and export it so the doctor preflight probes the ports the dev install actually binds. An external override still wins via the `:=` default. Documented the knob in tests/harness/README.md §9 alongside the other harness env flags. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
closes #39) `/v1/*` forwards upstream non-2xx bodies verbatim so OpenAI SDKs see the envelope shape they expect (`error.type`, `error.code`). `/api/*` always uses the hal0 envelope (`error.code`, `error.message`, `error.details`). Errors hal0 raises before reaching an upstream (auth, dispatch failure, slot not ready, payload validation) are always hal0-shaped even on /v1 — so the rule is really "hal0-produced → hal0 envelope; upstream-passed-through → OpenAI envelope", not strictly path-based. Added docs/api-errors.md with both shapes side-by-side and examples for 400, 401, 404, and 422. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…tream (closes #40) Internal task briefs occasionally referenced a non-existent `/api/slots/{name}/events` route. Audited `docs/`, `tests/`, and top-level markdown — no stale `/events` references remained; the cleanup must have happened in a prior sweep. CONTRIBUTING.md and docs/handoff-2026-05-15-autonomous.md already cite the canonical paths. Added a paragraph to the slots route module docstring explicitly enumerating both SSE endpoints so the next agent grepping for "slot SSE" lands on the right routes without bouncing through a stale brief. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
thinmintdev
added a commit
that referenced
this pull request
May 16, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Three independent low-risk doc/harness chores in one PR:
cli-test.shnow setsHAL0_DOCTOR_PORTS="${HAL0_DOCTOR_PORTS:-18080 13001}"so thecli-doctorrow probes the dev install's ports instead of the prod defaults (8080 + 3001). A co-resident prod install no longer poisons the harness exit code. README §9 documents the knob.docs/api-errors.mddocuments the hal0 envelope (/api/*+ any hal0-raised error) vs the OpenAI envelope (upstream-passthrough on/v1/*) side by side with 400/401/404/422 examples. The actual rule is "hal0-produced → hal0 envelope; upstream-passed-through → OpenAI envelope" — not strictly path-based — and the doc spells that out so OpenAI-SDK callers know to fall back when a dispatch-time failure surfaces a hal0 envelope on a/v1URL.docs/,tests/, and top-level markdown for the stale/api/slots/{name}/eventsreference — no occurrences remained; CONTRIBUTING and the 2026-05-15 handoff already use the canonical/state/streamand/logs/stream. Added a paragraph tosrc/hal0/api/routes/slots.py's module docstring enumerating both SSE endpoints so the next grep lands cleanly.Test plan
bash scripts/harness.shon a host with a co-resident prod install bound to 8080/3001 and confirm thecli-doctorrow ispass(ordeferredwith a non-collision rationale), notfail.HAL0_DOCTOR_PORTS=9999in front of the harness; confirm the doctor row probes 9999 (override wins).docs/api-errors.mdand confirm the rendered table + examples read correctly on GitHub.grep -rn "/api/slots/.*/events" --include="*.md" --include="*.py" .returns empty (current state).Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com