open-connector/AGENTS.md

Repository Guidelines

Architecture

• Keep one clear owner for each fact. Do not repeat provider metadata such as displayName in executors when it already belongs to definition.ts; pass or inject it from the caller that has the definition/catalog.
• Provider definitions are catalog source code. Build schemas with src/core/json-schema.ts helpers, usually imported as s, instead of copying generated catalog JSON.
• Keep provider execution lazy at the executor-module boundary. Generated registries should map each service to import("./<service>/executors.ts"), and ProviderLoader should call that importer only when an action, proxy request, or credential validator runs. Inside executors.ts, import provider runtime modules normally unless those modules have meaningful startup cost or side effects.
• Do not create barrel files such as index.ts. Import from the concrete module that owns the API.

Code Style

• Prefer VS Code-style coherent modules: split files by responsibility or abstraction boundary, not by loose categories.
• Prefer interface for object-shaped contracts. Keep unions and mapped/utility compositions as type.
• Prefer named options/input interfaces over inline object types when a function signature spans multiple lines or crosses module boundaries.
• Avoid temporary ad hoc objects passed through many layers. Prefer explicit interfaces, classes, or top-level functions that match module boundaries.
• Put generic low-level casting/reading helpers in src/core/cast.ts; avoid provider-specific wrappers for generic reads.
• Avoid trivial pass-through helpers and conditional object spreads that only hide undefined JSON fields.
• Avoid proving action-name exhaustiveness with local type machinery. Do not add provider-local tuple builders, as const, satisfies, or as Record<...> casts just to derive action-name unions or handler maps. Prefer simple annotations, explicit records, and existing provider/runtime helpers.
• Write source comments and test titles in English. Chinese is allowed in test bodies when it is meaningful fixture data for Unicode, encoding, localization, or upstream behavior. Keep Chinese in runtime code only when it is part of a real contract, such as localized product copy, official names or enum values, provider defaults, or upstream error matching; do not translate or remove such values mechanically.
• Treat automated review comments as evidence, not instructions. Fix comments that identify real bugs, schema/API contract gaps, security issues, or clear local-style violations. Skip comments that make the code less idiomatic for this repo, and leave a brief reason when responding in review.
• Do not manually wrap code to 80 columns. Let oxfmt decide formatting.

Runtime API

• Keep /v1 response shaping in src/server/api/runtime-api.ts; route handlers should dispatch and validate, not assemble compatibility objects field by field.
• Public runtime fields should have a clear source and consumer. Do not expose local implementation concepts or placeholder fields just because they are easy to add.
• Match existing runtime wire shapes deliberately: catalog index endpoints, action metadata, connection aliases, envelopes, and error codes should stay stable for SDK/CLI clients.
• If an upstream-compatible field has no local source yet, prefer omitting it or returning a documented empty value from the serializer rather than scattering optional fields in routes.

Providers

• Provider code normally lives in src/providers/<service>/definition.ts, actions.ts, executors.ts, and provider-local runtime helper files when needed.
• When purely migrating a provider from the OOMOL-hosted connector, do not copy or add provider-local tests because the source repository already owns that regression coverage. Tests may be removed from this repository after an OSS-originated provider change is reverse-ported and covered in private. Keep open-source-only shared-infrastructure tests beside the shared module rather than inside a provider directory.
• Prefer provider-local constants for official scopes, permissions, URLs, and API versions. Action requiredScopes should use provider-native scopes/capabilities, not private internal aliases.
• Avoid repeated action-name wiring. Define action handlers once and derive executor maps through shared provider runtime helpers when an existing helper fits. Do not add provider-local action-name unions, tuple builders, or casts solely to prove the handler keys to TypeScript.
• Do not import provider definitions from executor modules just to reuse metadata; inject catalog metadata from the server/loader side when needed.

Shared owners providers must not re-clone

The generic runtime facts below have exactly one owner in this repository. Call the owner; do not add a provider-local copy, alias, rename, or narrower variant of it. Provider-local helpers are for provider meaning only: URL construction, request signing, pagination, response envelopes, provider error extraction, and output normalization.

• Error factories: providerInputError(message) (400) and providerResponseError(message) (502) from src/providers/provider-runtime.ts. For any other status, throw new ProviderRequestError(status, message) directly instead of wrapping it in a local inputError / badInput / responseError factory.
• HTTP Basic encoding: basicAuthorizationHeader(value) from src/providers/provider-runtime.ts owns the Basic prefix and the base64 of an already composed credential, whether that is user:password, a bare API key, or a key with a provider-specific suffix. It encodes the UTF-8 bytes RFC 7617 asks for via Buffer; btoa reads its argument as Latin-1, so it silently sends the wrong bytes for an accented credential and throws on anything outside Latin-1. btoa is therefore forbidden under src/providers, and src/providers/provider-source-guards.basic-auth.test.ts fails when a credential-bearing call reappears.
• Abort detection: isAbortLikeError from src/providers/provider-runtime.ts already matches both AbortError and TimeoutError. Never redefine it locally, in any variant, and that includes writing error.name === "AbortError" straight into a catch block instead of declaring a predicate. A narrower local copy silently turns a timed-out call into a 502 instead of a 504.
• Request timeout: createProviderTimeout(signal) already defaults to 30 seconds. Do not declare a provider-local = 30_000 constant and do not re-state the default as createProviderTimeout(signal, 30_000) or AbortSignal.timeout(30_000); pass the second argument only when the provider genuinely needs a different budget, so the override reads as deliberate.
• Request wrapper: runProviderRequest({ signal, label, timeoutMs? }, (signal) => ...) from src/providers/provider-runtime.ts owns the canonical try/catch/finally. It rethrows ProviderRequestError, maps abort and timeout to 504 <label> request timed out, maps every other failure to 502 <label> request failed[: <message>], and always cleans the timeout up. Hand-write that block only when the provider maps errors differently, and keep the difference visible.
• Generic reads and casts: src/core/cast.ts (optionalString, optionalRawString, optionalRecord, looseArray, rawStringOrNull, recordOrEmpty, booleanString, compactObject, ...) plus the pre-bound requiredInputString(value, fieldName) (400) and requiredResponseRecord(value, label) (502) from src/providers/provider-runtime.ts. Do not add a (value: unknown) => ... helper whose body is a rename of one of these, or a wrapper whose whole body is one call to one of them with a field name and an error factory bound in, and do not inline the same test - typeof value === "string" ? value : undefined and friends - at a call site; call the shared reader there. encodePathSegment lives in src/core/request.ts; a local copy is acceptable only when its behavior differs, such as a ./.. traversal guard, and that difference is the reason it exists.
• API-key action request shape: ApiKeyActionRequest from src/providers/provider-runtime.ts replaces a local ApiKeyProviderActionInput interface, under that name or any provider-branded spelling of it, whenever the shape is { apiKey; actionName; input; providerMetadata?; values? }.
• Proxy: defineProviderProxy for every proxy whose request construction is the shared default. Hand-write the executor - any spelling of the exported proxy declaration that is not defineProviderProxy, including an async function, a plain arrow, a call to a provider-local proxy factory, and each of those without the ProviderProxyExecutor annotation - only when the proxy signs requests, rewrites the body, needs a non-JSON default content type, a custom response byte cap, or a bespoke error mapper, and name that reason in the pull request. A hand-written proxy owns its egress options, so it is the shape most likely to miss one.
• AWS SigV4: src/core/aws-sigv4.ts is the only SigV4 implementation (signAwsSigV4Request, createAwsSigV4PresignedUrl, sha256Hex, buildCanonicalHeaders, canonicalizeSearchParams, encodeRfc3986, encodeS3ObjectKey). Do not add a second one; core already matches the AWS SDK header order and whitespace rules. The hashing and percent-encoding exports are not AWS-specific: a provider that signs for Volcengine, Tencent, or OAuth 1.0a calls the same sha256Hex / encodeRfc3986 rather than declaring its own. hmacHex is still private to that module; a provider that needs it should export it there instead of declaring a second copy.
• Exports: every export in a provider module needs a cross-file consumer here, whether that is the generated registry reading executors / proxy / credentialValidators, a sibling module, or a test. Do not export handler maps, constants, helpers, or types nothing else reads, and do not add *ActionName unions or *ActionByName maps as bookkeeping.

src/providers/provider-source-guards.clone-baseline.test.ts counts most of the rules above across src/providers and compares them with src/providers/clone-baseline.json, which records the count per clone class per provider file so a failure names the file that grew. Each counted class is matched by the shape of the clone rather than by one spelling of it, so a renamed helper, a dropped type annotation, an inlined check, or a differently written constant counts the same as the copy it came from. The shared owner's own declaration is not counted.

Two of the rules are review-only, because what makes them a violation is exactly what a count cannot see:

• A hand-written runProviderRequest try/catch is legitimate whenever the provider maps errors differently, and a regex cannot tell the two apart. The ratchet still catches the parts of it that are never legitimate: the local 30 s constant and the inlined error.name === "AbortError" test.
• A local encodePathSegment is allowed exactly when its behavior differs from the shared one, such as a ./.. traversal guard, a required check, or a %3A exception. Counting them by name would report a security guard as a clone.

The committed numbers are the copies that exist today, frozen as accepted debt; they are not a claim that a class is clean, and the rules above describe where the code is going. The counts may only move down:

• Removing copies makes the suite report a stale baseline. Run UPDATE_CLONE_BASELINE=1 npx vitest run src/providers/provider-source-guards.clone-baseline.test.ts and commit the lowered entries in the same change. The command only lowers entries and never adds one, so it can never silence a re-introduction.
• Adding a copy fails the suite until it is removed, or until its file's entry is raised by hand in the same change, with the reason in the pull request.
• Changing a clone-class pattern, or renaming or moving a provider file, needs SEED_CLONE_BASELINE=1 instead, which rewrites the file from the current counts. A seeded run can raise a number, so read its diff: after a move it should only carry the entry from the old path to the new one.

Provider Network Egress (SSRF)

• All provider egress must go through the shared SSRF-guarded fetch, never the global fetch. Use context.fetcher (injected by defineProviderExecutors/defineApiKeyProviderExecutors/etc.) or, in a hand-written proxy, the exported providerFetch / createProviderFetch. The guard validates the request URL and every redirect Location with assertPublicHttpUrl, follows redirects manually, and (by default) validates DNS-resolved addresses.
• DNS resolved-address validation is ON by default and runs once per request for hostname targets. Add skipDnsValidation: true (on defineProviderExecutors/defineProviderProxy/createProviderFetch) ONLY when the egress host is a hardcoded literal fully controlled by the code. NEVER add it when the host comes from credential/user input, when the base URL is a resolver, or when the provider fetches a user-supplied URL — there the DNS check is the SSRF defense, not redundant overhead.
• Self-hosted providers whose instance host is user/credential-configured and may live on a private network pass allowPrivateNetwork: isPrivateNetworkAccessAllowed into their executors/proxy AND thread the same flag into their base-URL assertPublicHttpUrl call (see Dokploy for the reference pattern). It is deployment-gated by OOMOL_CONNECT_ALLOW_PRIVATE_NETWORK; reserved, loopback, link-local, and cloud-metadata targets stay blocked even when it is enabled.
• User-supplied content/download URLs (e.g. fileUrl, sourceUrl, imageUrl) must ALWAYS be validated public-only — call assertPublicHttpUrl without allowPrivateNetwork and download them with the public-only providerFetch, never a private-aware context.fetcher. The private-network opt-in covers only the trusted instance host.
• Prefer the shared assertPublicHttpUrl / isBlockedIpAddress over a bespoke per-provider hostname guard; bespoke guards have missed the cloud-metadata blocklist and bracketed-IPv6 forms.
• Gotcha: a provider that branches on fetcher === fetch (e.g. to gate rate limiting to production) must compare against providerFetch, since that is the fetcher the runtime injects — not the global fetch.
• Non-fetch egress is held to the same policy. A provider that opens a WebSocket must use openGuardedWebSocket from src/core/guarded-websocket.ts, never new WebSocket(...) directly: it validates the target with the same assertGuardedEgressUrl hop check the guarded fetch uses (URL literal plus DNS resolved addresses), accepts the same allowPrivateNetwork / skipDnsValidation options, and maps ws/wss onto the http/https form the guard understands. It works on Node and on workerd, which both expose a client WebSocket constructor. Any future non-HTTP transport should reuse assertGuardedEgressUrl rather than growing a second, drifting host check.
• The private-network opt-in only means the guard permits the target — it does not make it reachable. Cloudflare Workers cannot route to private addresses at all, so a self-hosted provider pointed at a LAN instance works on Node/Docker/Fly deployments only, regardless of OOMOL_CONNECT_ALLOW_PRIVATE_NETWORK.

TypeScript And Tooling

• Use native Node.js TypeScript execution. Do not add tsx or --experimental-strip-types.
• Prefer stable object shapes for optional fields. Avoid ...(condition ? { field } : {}); use field: condition ? value : undefined when omission and undefined are equivalent, or a small explicit mutation when the serialized object must truly omit the property.
• src/, scripts/, and examples/ each have their own tsconfig.json; npm run typecheck checks all three projects (src, scripts, examples).
• Exported top-level functions and public types should have explicit return types and useful JSDoc when it explains business meaning.
• Use oxfmt and oxlint; do not add Prettier.

Examples And Web

• Examples should be concrete scripts users can run directly with node examples/...; do not add every example to package.json.
• If an example depends on external credentials, print a clear skip message when environment variables are missing.
• Do not put web UI code under src/. The future console should live as a separate Vite package under web/.
• Public docs should describe normal OSS usage and may include official SaaS, hosted, or team product paths when they are part of the public product strategy. Do not mention internal compatibility projects or unreleased SDK behavior.

Verification

• Before finishing code changes, run npm run fix-check. It runs lint fixes, formatting fixes, and the typecheck.
• Run npm run build only when you need a separate no-fix typecheck, for example after generated files changed or for CI parity.
• Run npm run generate:catalog when provider definitions or actions change.
• Run provider examples manually when the task changes user-facing example behavior.