@sentropic/llm-mesh

Provider-agnostic model runtime, enrollment, and routing control plane.

@sentropic/llm-mesh owns provider/model capabilities, enrolled account eligibility, credentials, health, routing policy, affinity, and the versioned model-equivalence council. It returns opaque route plans and prepared attempts; neither a gateway nor another consumer receives provider credentials or raw account identifiers.

Public Scope

• Providers: OpenAI, Google Gemini, Anthropic Claude, Mistral, Cohere.
• Auth sources: direct token, user token, workspace token, environment token, Codex account, Cloud Code account, and Claude Code account.
• Normalized stream events: reasoning_delta, content_delta, tool_call_start, tool_call_delta, tool_call_result, status, error, done.
• Provider adapters: OpenAI, Gemini, Anthropic Claude, Mistral, and Cohere.
• Enrolled runtimes: CodexRuntimeClient and CloudCodeRuntimeClient execute canonical requests without exposing their account tokens.
• Routing strategies: last successfully enrolled first (default), ordered, or round-robin across new affinities only, with per-model/capability/intent rules.

Caller authentication, wire translation, financial metering, and response commitment remain outside this package. CLI enrollment uses an encrypted local keyring; portal mode remains injection-only. Override the CLI keyring directory with SENTROPIC_LLM_MESH_KEYRING_DIR when runtime isolation requires it.

CloudCodeRuntimeClient projects function parameter schemas onto the JSON Schema subset accepted by the Cloud Code Gemini wire. Tool names, properties, required fields and supported constraints are preserved; unsupported validation-only keywords are omitted before dispatch rather than causing an upstream 400 for rich Claude Code tool catalogs.

Routing policy

DEFAULT_ROUTE_POLICY uses the latest successful enrollment, a strict sticky account, same-transport preference, at most three attempts, and a five-minute negative-health cache. retest-preferred is the default fallback mode: a failed preferred route is suppressed until its TTL expires, then tested again. one-way promotes a successful fallback instead. Override negativeCacheTtlMs between 1 second and 1 hour.

Suffixed Claude launch aliases expose the owner-ratified Codex and Cloud Code targets returned by createCanonicalTargetCandidatesResolver(). An ordered policy can therefore place either enrolled transport first and keep the other as bounded pre-byte fallback. Bare provider model ids remain provider-faithful; these explicit alias routes do not create general model equivalence.

Equivalent-account rotation is disabled by default. Enabling rotateEquivalentAccounts may move an affinity to another account and lose provider-side prompt/session cache continuity; such a move is exposed as an audited rebind with cacheContinuityRisk: true. Mesh preserves account and stable-session affinity, but does not claim or manage a provider prompt cache.

The built-in equivalence council fails closed: a model is either covered by fresh benchmark evidence or explicitly excluded. Update its pinned source and generated artifact together:

make refresh-llm-model-equivalences
make check-llm-model-equivalences

Create the gateway-facing planner from the same facade that owns enrollment:

import { createLlmMeshFacade } from '@sentropic/llm-mesh/facade';

const facade = createLlmMeshFacade({ mode: 'cli', configResolver });
const routePlanner = facade.createRoutePlanner(runtime, {
  affinityAudit: (event) => audit.write(event),
});

Every completed enrollment persists its ownerScopeRef. The planner lists and prepares only accounts whose owner scope exactly matches the authenticated VerifiedRoutingSubject; changing a bearer/session principal does not change that owner scope or its affinities. Older local keyring records that predate owner tagging fail closed unless the host explicitly binds them once:

const facade = createLlmMeshFacade({
  mode: 'cli',
  configResolver,
  legacyAccountOwnerScopeRef: stableLocalOwnerRef,
});

That migration option is only for pre-ownerScope local records. New enrollment always takes ownership from StartEnrollmentInput.ownerScope.

Cloud Code OAuth client rotation

The embedded Antigravity OAuth client credential is distributable client configuration, not a user access or refresh token. Source and npm artifacts are built from the same checked-in value.

Rotate it from a protected 0600 file, then bump the package version in the same pull request:

make rotate-llm-mesh-cloud-code-oauth \
  CLOUD_CODE_OAUTH_CLIENT_SECRET_FILE=/absolute/path/to/client-secret

Recovery from an official Antigravity binary is fail-closed and requires both the pinned binary checksum and the expected credential fingerprint:

make rotate-llm-mesh-cloud-code-oauth-from-agy \
  AGY_BINARY=/absolute/path/to/antigravity \
  AGY_BINARY_SHA256=<verified-binary-sha256> \
  CLOUD_CODE_OAUTH_EXPECTED_SHA256=<approved-credential-sha256>

Update the GitHub Actions secret LLM_MESH_CLOUD_CODE_OAUTH_CLIENT_SECRET before merging. The main-branch publish job rebuilds the package, compares source and dist to that protected reference, rejects credential fragments outside the intended module (including source maps), and only then publishes through npm OIDC provenance. The workflow never writes the value to logs.

Published versions are immutable. Keep the previous and replacement clients valid for an agreed grace period, or explicitly accept that revocation breaks enrollment for older package versions.