Imported from jtenner/metidos (core_plugins/therouter/AGENTS.md). Install upstream with npx skills add jtenner/metidos --skill therouter. Copyright stays with the author.

AGENTS for TheRouter

Purpose

First-party provider plugin for TheRouter. It registers Plugin System v1 model providers for TheRouter's OpenAI-compatible chat-completions transport and embedding API at https://api.therouter.ai/v1.

Source layout

• metidos-plugin.json: v1 manifest reviewed by the local operator; declares THEROUTER_API_KEY, the optional api_key plugin setting, network access to TheRouter model discovery and embeddings endpoints, and the therouter plus therouter_embeddings model providers.
• index.ts: plugin entry point that discovers models from /v1/models, returns OpenAI-compatible provider configurations with per-configuration piAuth records, and implements the Metidos embedding provider callback through /v1/embeddings.
• AGENTS.md: this guide.
• .data/: generated plugin data owned by Metidos; this plugin does not intentionally create files there.
• .logs/: generated plugin logs if enabled; discovery warnings may be logged there.
• .data-bak-*: generated reset backups; do not commit.

Root node_modules/ is forbidden.

Validation

1. Validate metidos-plugin.json against the Metidos Plugin Manifest v1 schema.
2. Run bun test src/bun/plugin/therouter-core-plugin.test.ts from the repository root.
3. Confirm no root node_modules/ exists.
4. Confirm imports are local or @metidos/plugin-api.

.data contents

This plugin has no durable plugin-owned data. If .data/ exists, it is runtime-created by Metidos and can be regenerated by Reset Plugin Data.

Safe .data inspection

• Prefer read-only inspection.
• Do not copy or print secret-bearing files if future changes add local credentials.
• Do not edit .data while the plugin sidecar is running unless this guide is updated with an explicit repair workflow.

Safe .data repair

There are no hand-repairable data files today. Prefer Metidos Reset Plugin Data for unknown .data contents; it should be safe because this plugin has no seed data or durable local state.

Reset behavior

Metidos Reset Plugin Data moves .data to .data-bak-{timestamp}, recreates .data, and restarts/reloads the plugin. No local configuration is recreated because credentials live in plugin settings or THEROUTER_API_KEY.

Secrets and logs

Secrets are provided through the optional secret plugin setting api_key or the secret env var THEROUTER_API_KEY. Do not log API keys, Authorization headers, prompts, embedding inputs, embedding vectors, model responses, or request payloads. Discovery failures may log bounded status/error messages only.

Credential precedence for discovery, inference, and embeddings is plugin api_key, then THEROUTER_API_KEY, as declared in the provider configuration piAuth records.

Embeddings and vector search

This plugin provides embedding models through metidos:provides_embeddings and the therouter_embeddings provider registration. The embed(context, request) callback sends the requested model id and input text to TheRouter's OpenAI-compatible /v1/embeddings endpoint and returns the first finite numeric vector from the response. Raw embedding input leaves the local machine for TheRouter; do not log it or copy it during inspection.

This plugin does not call metidos.embeddings.embed(...) as a consumer and does not store LanceDB vectors. It intentionally does not request metidos:can_embed, metidos:lancedb, or storage:write.

Context notes

Provider registration is initialization-only. Model discovery uses network:fetch against TheRouter's /v1/models endpoint during provider refresh. Embedding callbacks use network:fetch against /v1/embeddings. Runtime chat inference is performed by Pi using the registered OpenAI-compatible provider configuration.