Contributing

How to work on Meted.

git clone https://github.com/sous-software/meted.git
cd meted
pnpm install
pnpm build
pnpm test

Node 20.11 or later.

Before opening a pull request:

pnpm lint
pnpm typecheck
pnpm test
pnpm build

Required behavior

Please open an issue before changing any of these.

Meted is a proxy first. Engine failure means forwarding the original request unchanged. runEngine never throws.

Observe mode sets no ceiling. In observe, the upstream request body is unchanged apart from stream_options on a streaming request. There is a test; keep it passing.

Never raise a caller's ceiling. Lower it or leave it.

Measured and estimated stay separate. Anything derived from the engine is labelled estimated wherever it surfaces, and claimed reductions are always net of optimizer overhead.

The gateway holds no request history and makes no outbound call except to the configured provider. Per-request data reaches the embedding process through onRecord. A pull request that adds persistence to the request path, or a second outbound destination, needs an issue first.

Working on the baseline engine

packages/engine-interface/src/baseline/
├── features.ts     pure signal extraction
├── classify.ts     scored task signals, complexity bands
├── allocate.ts     budget modifiers and caps
└── taxonomy.ts     the numbers themselves

Two rules when tuning:

Sufficiency, not brevity. If a change makes answers smaller, show it does not make any of them truncate. meted eval --verbose lists under-allocations by prompt.
Add the case to the tests. Every classification the engine gets wrong is worth a line in baseline.test.ts.

The documented example is pinned in CI:

meted inspect "What is a semaphore?"  →  definition · simple · 38 / 64 / 96%

If a change moves those numbers, update the docs in the same pull request.

Adding evaluation prompts

packages/eval/src/builtin.ts is the source of truth.

pnpm --filter @meted/eval build
node packages/eval/scripts/emit-builtin.mjs

Prefer deterministic assertions, and bias new prompts towards cases where Meted could do damage.

Adding a provider

Implement ProviderAdapter and register it. See Provider adapters; packages/providers/src/openai.test.ts is the specification.

Reporting bugs

meted --version
node --version
meted inspect "<a prompt that reproduces it>"

meted inspect never contacts a provider, so its output is safe to paste publicly as long as the prompt itself is.

Security issues go to [email protected], not a public issue.