http-tool-bridge

Dual-language SDK for HTBP (HTTP Tool Bridge Protocol): expose functions as self-describing HTTP tool endpoints, FastAPI-style. The protocol core is extracted from tool-bridge; the protocol spec lives in HTBP RFC-0001.

Package	Registry	Language
@tokenroll/htbp	npm	TypeScript (fetch-native; Workers/Bun/Deno/Node)
htbp-sdk	PyPI (import htbp)	Python (pure ASGI; uvicorn/FastAPI)

Protocol surface

• GET {path}/~help — JSON HelpPayload by default; RFC-0001 text DSL with Accept: text/plain
• GET {path}/~skill — optional markdown guidance
• POST {path} — invoke a tool; responds {"resource", "result"}
• Errors: {"error": {"code", "message", "details?"}} with proper HTTP status
• ETag/304 revalidation and Cache-Control on control-plane documents
• Directory resources[].path links are always relative, so any subtree is mountable under any domain or base path

Cascading

Both SDKs support local nesting (app.mount("/docs", subApp)) and remote federation (app.remote("/ext", "https://.../~help")) — a remote node passes through ~help for any sub-path and proxies calls, never forwarding the inbound Authorization header. TS and Python servers federate to each other transparently.

Development

# TypeScript
cd packages/ts && npm install && npm test

# Python
cd packages/py && uv sync && uv run pytest

Cross-language conformance goldens live in fixtures/conformance/; both test suites assert against the same files (JSON deep-equal, text DSL byte-equal).

Releasing

• npm: tag ts-v* → .github/workflows/release-ts.yml
• PyPI: tag py-v* → .github/workflows/release-py.yml (trusted publishing)