Small contracts. Composable agents.

Use the hosted API directly, compose the Node packages, or stay inside the CLI. Every surface shares the same routing and permission contract.

Packages#

PackageUse it for

@tokensize/agent-clientShared local discovery, allowance, auth, routing, receipts and feedback.

@tokensize/cliTerminal commands and JSON/human-readable output.

@tokensize/mcpCodex-compatible stdio tools backed by the shared client.

@tokensize/opencodeTyped OpenCode tools with inspect-only execution in beta.

@tokensize/routerRuntime-neutral model selection with no infrastructure lock-in.

Hosted endpoints#

GET/v1/agent-catalog

Check service protocol compatibility and advertised harness support.

POST/v1/agent-routes

Submit task features and candidate metadata for an explainable route.

POST/v1/agent-feedback

Submit receipt-bound, content-free execution feedback.

POST/v1/feedback

Submit an idempotent provider/session outcome for Router Brain calibration; prompts and outputs are not accepted.

GET/.well-known/tokensize-agent.json

Discover the registration protocol, credential prefix and privacy boundary.

Configuration#

TOKENSIZE_API_URL=https://api.tokensize.dev
TOKENSIZE_API_KEY=ts_…                 # headless only
TOKENSIZE_HOME=~/.tokensize             # optional local store
TOKENSIZE_ROOT_HARNESS=codex            # embedding surface
TOKENSIZE_ROOT_ACTIVE=1                 # plugin root
TOKENSIZE_ALLOW_SUBSCRIPTION_HARNESSES=codex,claude

Never commit .dev.vars, provider keys or API keys. The browser callback is the recommended interactive setup.

Route request shape#

Contract v2 carries the client surface and active-root state explicitly. The hosted service is not a hidden quality signal or a permission authority.

{
  "schemaVersion": 2,
  "client": { "surface": "codex-plugin", "version": "0.3.0-beta.1" },
  "root": { "harness": "codex", "active": true },
  "routerMode": "metadata-only",
  "policy": { "objective": "balanced", "permissionCeiling": "inspect" }
}

Router Brain signal contract#

Learning is an optional input to the runtime-neutral router. Consumers supply signals; the package never collects telemetry.

{
  candidateId: "openai/gpt-5.5",
  taskBucket: "v1-…",              // coarse non-content features
  successProbability: 0.90,
  lowerBound: 0.61,                 // must be >= 0.55 to influence
  state: "calibrated",              // or canary | promoted
  successCount: 13,
  failureCount: 1,
  artifactVersion: "router-brain-v1"
}

States baseline, observing,quarantined and rolled-back are intentionally non-influential. Signals blend with static catalog quality and never replace safe-set, allowance or permission checks.