Package Exports

@hera-al/atn-proxy
@hera-al/atn-proxy/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@hera-al/atn-proxy) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@hera-al/atn-proxy

Part of Hera Artificial Life — an opinionated AI assistant platform that runs locally on your machine. This package provides the tool name translation proxy used by Hera agents to communicate with OpenAI-compatible endpoints. It can also be used independently in any Node.js project.

Anthropic Tool Name Proxy — sits between the Claude Agent SDK and OpenAI-compatible endpoints (e.g. OpenRouter), resolving the 64-character tool name limit.

Agent SDK  -->  ATN-Proxy (:4181)  -->  OpenRouter  -->  Model

What it does

Direction	Action
Request	Truncates `tools[].name` to 64 chars using a deterministic hash suffix
Request	Rewrites `?beta=true` query param into the `anthropic-beta` header
Request	Truncates `tool_use.name` in conversation history to match
Response	Remaps truncated tool names back to originals (stream + non-stream)
Response	Normalizes `usage{}` to Anthropic format (missing fields default to 0)
Response	Wraps non-JSON responses (HTML 404) into Anthropic-compatible errors
Response	Handles `/count_tokens` locally with a token estimate

Install

npm install -g @hera-al/atn-proxy

Or run from source:

git clone https://github.com/hera-artificial-life/hera-al.git
cd hera-al/atn-proxy
npm install
npm run build

Usage

# Start with defaults (port 4181, target openrouter.ai)
atn-proxy

# Custom port and verbose logging
atn-proxy --port 8080 --verbose

# Show all options
atn-proxy --help

Options

Flag	Default	Description
`--port <n>`	`4181` (env: `PORT`)	Listen port
`--target <url>`	`https://openrouter.ai`	Upstream endpoint
`--prefix <path>`	`/api`	Target path prefix
`--max-name <n>`	`64`	Max tool name length
`--logs <dir>`	`./logs`	Log directory
`--verbose`	off (env: `VERBOSE=1`)	Debug logging

Connect the Agent SDK

ANTHROPIC_BASE_URL=http://localhost:4181 \
ANTHROPIC_AUTH_TOKEN=sk-or-v1-xxx \
ANTHROPIC_API_KEY="" \
node your-agent.mjs

Logging

Logs are written to ./logs/atn-proxy.log with automatic rotation:

Max file size: 10 MB
Rotated files: up to 9 (atn-proxy.1.log ... atn-proxy.9.log)

How tool name truncation works

When a tool name exceeds the max length, ATN-Proxy generates a deterministic short name by keeping a readable prefix and appending an 8-char SHA-256 hash:

mcp__very-long-server-name__very_long_tool_name
  --> mcp__very-long-server-name__very_long_t_a1b2c3d4

The mapping is maintained in memory for the proxy session. Response tool names are automatically restored to the originals before reaching the SDK.

License

MIT