skillstate-proxy

skillstate-proxy is a local HTTP proxy intended for agent workflows that can express their progress as explicit structured state. It sits between a client and a configured model provider, builds context from the task specification, the session's JSON state and the latest observation, then extracts a state_patch from the model's response. The README frames token reduction as workload-dependent and explicitly states that savings, latency, accuracy and provider compatibility are not guaranteed. Installation uses npm (Node.js 20 or newer). The executable is skillstate, also available as skillstate-proxy. Configuration is via environment variables such as SKILLSTATE_UPSTREAM, SKILLSTATE_API_KEY, SKILLSTATE_PORT (default 127.0.0.1:8789), SKILLSTATE_SCHEMA, SKILLSTATE_INITIAL_STATE, SKILLSTATE_CONFIG and SKILLSTATE_VERBOSE, plus CLI flags --config, --upstream, --port, --schema and --verbose. Precedence is CLI flags, environment variables, configuration file, then defaults. A compatible chat client points at http://127.0.0.1:8789/v1. The state contract merges patches by replacing arrays, recursively merging objects, and deleting a key when its patch value is null. The README stresses this is not a lossless transcript archive: facts not preserved in state may be unavailable later, and a separate audit record is advised when verbatim evidence matters. Allowed key lists do not bound value or observation size. HTTP surface includes POST /v1/chat/completions, POST /v1/messages (Anthropic-format translation), GET /v1/models, GET /health, GET /state (with ?session=ID), DELETE /state?session=ID and GET /cost. The README cautions that an implemented route is not proof every SDK feature works, and recommends testing streaming, tool-call correlation, concurrent sessions, retries and cancellation against the exact client, provider and model. Optional per-upstream rpm/tpm settings use a local one-minute rolling window and are not provider-side quotas or distributed limiters. Verification from source uses npm ci, npm run build and npm test with the committed package-lock.json; CI checks Node.js 20, 22 and 24. Optional static documentation layout checks use Python Playwright. Benchmarks (conversation and tool-loop) require explicit provider configuration and can cost money; the README advises retaining revision, workload, model, schema, raw usage, retries, quality scores and failures with any result, and comparing total billed input/output costs. The project references the SKILL.state paper (arXiv:2608.26263) and notes research results do not establish this implementation's accuracy or universal compatibility. It is MIT licensed, not affiliated with OpenAI or Anthropic, and the license does not cover upstream inference or hosting. State is persisted locally and may contain sensitive task information; the upstream receives the rewritten context, so the listener should be kept private. The README states the project is not a multi-tenant security boundary merely because it has session IDs.