Coding style
This guide owns the coding conventions for WednesdayAI core. For the PR gate and contribution workflow, see Contributing. For test conventions, see Testing.Principles
Follow the Development Principles in Contributing. In short:- Reuse maintained packages already in the stack instead of building from scratch.
- Fix bug classes rather than instances. Use real parsers, not regex, for structured formats.
- Assert causes in tests.
- Keep scope to the goal.
- Block reviews only on in-scope correctness and security.
Language and structure
- Language: TypeScript ESM with
strict: true. No@ts-nocheck. Do not disableno-explicit-any; fix the root cause. - Style: functional and module pattern dominant. Use classes for channel adapters and stateful lifecycle managers.
- Dependency injection:
createDefaultDeps()insrc/cli/deps.tsreturns a plain dependency object. Commands receive it as a parameter. There is no IoC framework. - No prototype mutation: never use
applyPrototypeMixins,Object.definePropertyon.prototype, orClass.prototypeexports. Use explicit inheritance or composition. Get explicit approval first. - Comments: write them only for non-obvious logic such as hidden constraints, workarounds, and subtle invariants. Do not write docblocks that restate what the code does.
- File size: keep files under 500 lines of code.
pnpm check:loc(part ofpnpm check) runsscripts/check-core-loc.ts, the core LOC per-file ratchet from ADR 1440: it blocks a coresrc/file over 800 lines that is not grandfathered inscripts/core-loc-baseline.json, and a grandfathered file that grew past its recorded ceiling. The core total is reported, not gated (ADR 1967).pnpm check:loc --updateonly lowers per-file entries; raising one needs a written justification in the PR. - Formatting: run
pnpm checkbefore committing. Resolve formatting-only diffs without asking. - Naming: use WednesdayAI in user-facing docs and headings.
wednesdayaiis the primary binary name andopenclawis a backward-compatible legacy alias under staged removal (ADR 2057). Config keys and internal identifiers stayopenclaw. - Imports: use the
.jsextension for relative ESM imports,import type { X }for type-only imports, and import directly from the original module. Do not create files that only re-export another file. - Process-scoped state across the SDK bundle: gateway and conformance plugin loads hand the plugin the host’s own SDK instances through jiti
virtualModules(ADR 1032), but a load that skips that handoff, for example a directloadOpenClawPluginscall, still runs the plugin against its own jiti copy of the publishedwednesdayai/plugin-sdktsdown bundle; plain module-scope mutable state would then split per copy. Any module-scope mutable state reachable through the SDK must useresolveProcessScopedMap(fromwednesdayai/plugin-sdk/process-scoped-map) or be routed through anapi.runtimemember instead. Vitest aliases the SDK tosrc/, so test suites run one module graph and cannot see the split: guard split-sensitive bindings withvi.resetModules()plus a dynamic re-import in a*.process-scope.test.tstest (conformance example:extensions/telegram/src/conformance.split-graph.test.ts). The legacyopenclaw/plugin-sdkspecifier still loads (ADR 2057).
Do not duplicate helpers
Before writing a formatter, utility, or helper, search for an existing implementation and import it. If a function already exists, do not create a copy in another file.
Never create local
formatAge, formatDuration, or formatElapsedTime functions.
Script entry points
Scripts underscripts/ decide whether to run main() with isDirectRun(import.meta.url) from scripts/lib/direct-run.mjs. Guards built on scripts/lib/ts-guard-utils.mjs get it through runAsScript(import.meta.url, main).
Do not compare import.meta.url with process.argv[1] directly. Node resolves symlinks in import.meta.url but keeps process.argv[1] as the caller typed it. A script launched through a symlinked path (the macOS temp directory /var is a symlink to /private/var, or a symlinked checkout) then skips main() and exits 0 without doing anything. isDirectRun resolves both sides with realpathSync.
pnpm lint:scripts:direct-run (part of pnpm check) runs scripts/check-scripts-direct-run.mjs. It fails on any process.argv[1] read in scripts/ outside the helper and test files.
Colors and terminal output
Two modules split the work.src/terminal/palette.ts holds the color tokens. src/terminal/theme.ts wraps chalk around those tokens and exposes the semantic helpers. Use theme for output and never hardcode ANSI escapes.
Logging
Create one subsystem logger at module top and use it instead ofconsole.log in production code:
Tool input schemas (TypeBox)
Tool input schemas use@sinclair/typebox. Several model providers reject schema constructs that TypeBox can produce, so keep schemas flat:
- No
Type.Union, and noanyOf,oneOf, orallOfin tool input schemas. - Use
stringEnumandoptionalStringEnum(aType.Unsafeenum, insrc/agents/schema/typebox.ts) for string enumerations. - Use
Type.Optional(...)instead of... | null. - Never use
formatas a raw property name. Some validators reject it.
Toolchain
Notes:
extensions/is excluded from Oxlint (ignorePatterns). Extensions manage their own lint.pnpm builddoes not type-check. Runpnpm tsgofor that.pnpm checkruns format check,tsgo,tsgo:web,tsgo:control, Oxlint, the custom lint scripts below, the contract-surface check (lint:contracts:surface), the installer-host guard, the version-source guard (version:guard), and the core LOC per-file ratchet (check:loc). The pre-push hook runs it (ADR 0118).lint:extensions:no-core-tables(part ofpnpm check) runsscripts/check-extension-core-table-access.ts. It fails on any reference fromextensions/to a core session table. Plugins own their tables (Postgres schemaplugin_<id>, SQLite prefixplugin_<id>_) and read conversation data through the plugin-sdk; allowlist entries are test-harness only, each naming the finding that tracks its removal.lint:sessions:no-sessionkey-identity-parse(part ofpnpm check) runsscripts/check-no-sessionkey-identity-parse.mjs. It fails on non-test code undersrc/,extensions/, andapps/that derives channel, account, peer kind/id, group, or user identity fromsessionKeytext: splitting, regex matching, or identity-segment string probes on the key, or any access onparseAgentSessionKey(...).rest. Identity comes from the persisted session actor (and the SDKruntimeIdentityfields), never from parsing the key;sessionKeyis an opaque bucket id. The rule lives in ADR 0081 (dev-docs/adr/0081-config-independent-actor-identity.md); plugin-facing guidance is Session identity keying. A failure prints one- <path>:<line> <rule>line per violation (R1/R2/R3); a file the guard cannot scan reports<path>:0 SCAN-ERRORand must be fixed or reported, not ignored. The structural owner files (src/sessions/session-key-utils.ts,src/routing/session-key.ts,src/config/sessions/ctx-identity-backfill.ts,src/shared/session-visibility.ts,apps/web/src/ui/session-key-shape.ts) are exempt.lint:adr:unique-numbers(part ofpnpm check) runsscripts/check-adr-numbers.mjs. It fails when two files indev-docs/adr/share a number, or when a file there is not a flat<N>-<lowercase-slug>.md. A new ADR’s number is the WednesdayAI-core issue or PR number that carries the decision, zero-padded to 4 digits; ADRs 0001–0122 keep their sequential numbers (ADR 1577,dev-docs/adr/1577-adr-numbers-are-github-numbers.md). If the guard fails on your branch, rename your ADR to your issue or PR number.version:guard(part ofpnpm check) runsscripts/check-version-source.ts. It fails when thepackage.jsonversiondiffers from the version at the merge base ofHEADandorigin/main(GITHUB_BASE_REFoverridesmain); only the release-please PR bumps versions, andrelease-please--*branches are skipped. It fetchesorigin/<base>when that ref is missing, and refreshes it once before reporting a mismatch so a stale local ref cannot cause a false failure. It never fetches with--depth, so it cannot make a clone shallow (ADR 2403). Every failure, including a missing or invalidpackage.jsonin the working tree or at the merge base, exits 1 with oneVersion-source guard FAILED:line.