Working in this repository

Jason is a local-first, vendor-neutral SDR domain runtime: a .NET runtime process that owns durable campaign state and exposes a loopback Runtime API, a CLI that is a pure client of that API, JavaScript plugins that execute provider operations in a separate plugin-host process, and skills that teach AI agents the job. docs/architecture.md is the design authority for anything not covered here.

Layout

• dotnet/ — all C#: Jason.slnx, src/Jason.App (the single executable; picks the mode from argv), src/Jason.Cli, src/Jason.Runtime, src/Jason.PluginHost, src/Jason.Contracts, tests/ (one xUnit project per source project).
• plugins/ — plugin marketplace. skills/runtime/, skills/business/ — skill packs. docs/ — maintained documentation only.
• ui/ — the browser UI: a Preact client of the Runtime API, built into the release asset jason-ui.zip; ui/README.md says how it is built and tested.
• LICENSE — MIT, for everything in the repository, the runtime included; every archive carries it as LICENSE, beside the executable and THIRD-PARTY-NOTICES.
• global.json at the root pins the SDK; run every command from the repository root.

Commands

Building, testing, migrations, the UI's checks, and running a build of this checkout with its own data, skills and UI: DEVELOPMENT.md.

Boundaries that the build enforces

• Jason.Cli references only Jason.Contracts and the HTTP client. Never Jason.Runtime, EF Core or SQLite: the CLI never touches the database, it talks to the Runtime API.
• Plugin JavaScript never runs inside the long-lived runtime process; it runs in the plugin-host mode of the same executable. Jason.Runtime references neither Jint nor Jason.PluginHost; Jason.PluginHost never references Jason.Runtime; manifests are read with YamlDotNet in Jason.Runtime only, so the contracts, the CLI and the host stay YAML-free.
• The dispatcher is deterministic runtime code; it never reads the meaning of a work item's context.
• Every child process is made by ChildProcess.StartInfo and started by ChildProcess.Start, with no console window of its own and no shell, and on Windows with the starting thread's error mode keeping the boxes the start itself raises, for a file that is no program image, off the desktop (StartErrorMode); a started child's own loader errors, a missing DLL say, follow the process error mode it inherits; a guard reads the compiled IL of every production assembly and refuses a ProcessStartInfo made anywhere else, a Process.Start anywhere else, a write to CreateNoWindow or UseShellExecute, Process.Start from a file name, and a read of a process's StartInfo. Reflection, expression trees and new T() are beyond what it reads.
• Publication: this repository is public. Every file in it, every commit message and every pull request's title and body is read publicly, so none of them carries a tracker key outside a branch name, an attribution trailer, a pointer to an internal note, plan or system, a link to a private repository, a real person's name or account in the text (git's author fields and CODEOWNERS aside), or a secret. RepositoryHygieneTests holds every file of the tree to the patterns a machine can check, and every link to a path of this repository to a file the tree holds; the hygiene.yml workflow holds each pull request's added lines, title and body to the same patterns. The rest is the author's to keep.
• Package versions live in dotnet/Directory.Packages.props only. THIRD-PARTY-NOTICES covers every package of Jason.App's closure and the runtime packs the executable carries; after a package or SDK change ThirdPartyNoticesTests is red until pwsh .github/scripts/Write-ThirdPartyNotices.ps1 writes it again.
• Warnings are errors. Every test runs offline and uses an isolated temporary data directory.
• The UI is one more consumer of the Runtime API, and Jason stays command-line first and agent first. Three tests for anything the UI needs from the runtime: it gets a CLI verb that makes sense typed by a person or an agent (the one door outside the catalog is the pairing exchange POST /ui/session); it returns facts, never views; the runtime never knows a screen exists — no route named after a page, no state, preference or cache kept for it, and with <data>/ui/ absent the runtime is unchanged (UiGuardTests). A UI token has the run token's rights: one level of trust, the machine's user. The UI is tested in three layers (ui/README.md, "Testing"): unit tests of dense logic in Node, screen tests against the exchanges the runtime's own tests recorded under docs/api/fixtures/ (ApiFixtures, held one-to-one with the files and rewritten only under JASON_UPDATE_FIXTURES=1), and a browser smoke of the seams alone. Six guards hold the layers: the unit project runs without a DOM and may not import Preact; no .json under ui/ but the configuration; a dependency allowlist; the fixture catalog; only the smoke's harness starts processes; one CI job runs all of it.

Conventions

• Terminology: plugin (not adapter), WorkItem (not Task), channels (not handles). Skills, memory files, named preferences, campaign context, role notes and learned practice are six distinct knowledge concepts; do not blur them. Membership in a Jason campaign is local; campaign.enroll — a later, provider-side, approval-gated act — is a different thing.
• Runtime API: RPC style, POST /v1/{noun}.{verb} for everything, reads included. Success is 200 with a bare DTO; errors are {"error":{"code","message","retryable"}} with snake_case codes. JSON is snake_case, enums are snake_case strings, timestamps are ISO-8601 UTC, public ids are prefixed ULIDs (cmp_…, wi_…, att_…, rol_…). Partial patches distinguish absent from null (Optional<T>); lists paginate with limit/cursor; every mutating request may carry actor and reason. campaign.create and workitem.create also take a caller's idempotency_key, kept on the entity it created and never derived by the runtime or the CLI (docs/work-execution.md).
• Work execution: work items move through one transition table (WorkItemTransitions) and end through one routine (AttemptOutcomes); never write a status elsewhere. The attempt id is the fencing token: executor operations change state through a single guarded UPDATE, never read-then-write. The dispatcher claims inside BEGIN IMMEDIATE, at most as many items as it has free handler slots, one per campaign per scan. The launch envelope goes to the child on stdin; nothing goes on argv, and the capability token never reaches a child's environment, a work-directory file or an attempt row (redacted). docs/work-execution.md is the contract.
• Canonical operations: a contract is data, not code. One JSON document per operation lives under docs/contracts/operations/ and is embedded into Jason.Contracts as a resource, so the file a plugin author reads is the file the runtime enforces — never write a second copy of a rule that document already states. Schemas are the restricted JSON Schema dialect SchemaValidator publishes; a keyword outside that vocabulary is refused rather than ignored. context.input is the reserved work-item context key carrying an operation's arguments: it is validated at workitem.create, and again at workitem.update whenever a patch names the key. The fixtures under docs/contracts/fixtures/ are executed by tests, so a document and the code cannot drift apart. docs/contracts/README.md is the contract. The delivery contract, notification.send, is a family of its own under docs/contracts/notifications/, embedded the same way and never in the operation catalog.
• Routing: which plugin performs an operation for a campaign is a route, resolved by a pure function over an immutable snapshot — campaign operation override, campaign default, global operation override, global default, with exact masking and no fallback to another plugin. Routes are frozen by the same reload that freezes plugins: the Routes section of settings.json is read only there and at startup, route.set/route.unset copy the global half from the active snapshot, and a bad route rejects the whole reload. The claim is fail-closed: twenty checks in one published order, one code per reason, decided before a child exists, with the attempt kept. A binding names an account and never a credential. A provider identifier is pinned once and never overwritten — a different value is recorded beside it as a divergence and the attempt still succeeds. Provenance is written at the claim and completed at the end; nothing rewrites it. docs/routing.md is the contract.
• Plugins: a package is ~/.jason/plugins/<id>/ with plugin.yaml, main.js and optional modules; the directory name is the id. The manifest is validated against one fixed vocabulary of problem codes — package problems reject the whole reload and keep the previous snapshot, and so does a settings file the reload cannot read (settings_file_unreadable; one that is not there rejects nothing); the four executable_* ones and, at a start only, probe_timed_out are environmental and only make that plugin unavailable. Every package has a sha256: content digest that the child recomputes before it runs anything. The invocation goes to the child on stdin, exactly one outcome comes back on stdout, diagnostics are JSON Lines on stderr, and the exit code says only whether the protocol completed (0 outcome, 2 usage, 3 rejected, 4 host failure). Declaration is not permission: capabilities are requested by the manifest and granted under Plugins:Grants:<id>, resolved and frozen at each load; a manifest's any_granted_host lets a person grant a host it does not declare, and * still means the declared hosts alone. Configuration is Plugins:Config:<id>: text only, frozen at each load, handed on stdin and read with host.config, a secret of the invocation, never in a package. A failure carries one of five classes — transient is retried, permanent, validation and blocked are final, and ambiguous says the provider may already have acted, so it is repeated only where the operation's own contract declares that repeating it is safe or that a recovery read makes it safe. An activated load journals plugins_reloaded; there is no plugin.invoke operation. docs/plugins.md is the contract.
• Inbound sync: a scan step between the lease enforcer and the summon reads each active campaign routed to a plugin that reads conversations, and linked there, once per cadence — one conversation.list work item per page — and writes one reserved inbound_reply_observed line per thread that moved — identifiers, moments and the provider's flags, never a subject, a preview or a name — said once per campaign by a key. It interprets nothing; the line is a default manager trigger. A respond step between it and the summon reads those lines above a per-campaign watermark, whichever writer said them, and for a thread the campaign holds by its own pin queues a conversation.get and a responder created waiting on it — one open responder per thread, a further move patched onto its inbound_reply — with identifiers and moments only, and never an idempotency key; its conversation.list items sit ten above Responder:Priority, so the sends wait and detection does not. docs/inbound-sync.md is the contract.
• Events: a third contract family, events.read under docs/contracts/events/, embedded like the delivery contract and never in the operation catalog. A provider that declares contracts.events reads an account by its own cursor, which the runtime stores per plugin and binding identity and never parses; a read pins nothing. What is read lands in an append-only store — event_sources, events, event_attributions, under the journal's three guards — each event once by a key per plugin, and an event no pin matches is kept. An event reaches a campaign only by the campaign identifier its operations pinned, decided once when it is stored, as a reserved line: a thread the other side moved as inbound_reply_observed under inbound sync's key, every other kind as provider_event_observed. A scan step between the lease enforcer and inbound sync hands one read at a time to a reader off the scan — never a work item or a handler slot — for every account a route binds, on Dispatcher:EventsCadenceSeconds, thirty days deep, a span older than that said once as events_gap_observed; inbound sync skips a campaign routed to such a plugin only where an event would reach it by the campaign-pin rule — one function, which the store attributes by — and only while that account's last read that succeeded started within the shorter of two cadences and the look-back. A person may ask for a span of an account to be read again (events.backfill: at most 366 days back, eight waiting an account), read only in a scan where every account is current, by a cursor of its own that never moves the account's; events.signal names an account and nothing else and brings its next read forward, never within a minute of the last; events.sources is the accounts' record and never answers a cursor. docs/events.md is the contract.
• Notifications: a parked approval, a raised question, failed protective work, an account whose events were not read, an open provider block and an item held at a daily limit of launches are notified as a pointer — counts and where to look — by a scan step after the dispatch, delivered off the scan and recorded in a reserved notification_sent line. docs/notifications.md is the contract.
• Projects and preferences: every campaign is in exactly one project — the default one, which every installation has, unless it names another — and a project's slug is unique and never changes. The client is the installation and has no entity; what a person states about it is a named preference, a fourth contract family under docs/contracts/preferences/ embedded like the others and never in the operation catalog: one value per key for the installation, checked against the key's schema, set and unset by a named person only, and journaled by its size and hash, never its value. The client, each project and each campaign have a folder under the harness root, made at the first create that needs it, with a marker naming its level and id and the person's memory file, AGENTS.md, beside a one-line import file for every host that reads a file of another name (CLAUDE.md for Claude Code); the runtime writes structure only — never a word of a memory file, never a delete, never git — and moves a campaign's folder by one rename when the campaign changes project, or refuses the move. A path is recorded on the entity; a folder is known by its marker, never its name, and a folder the person moves is recorded again only by project.link, which reads the project's folder and each folder directly in its campaigns/ and never takes a campaign's project from a folder. A verb that takes a project and is given none takes it from the nearest marker above the folder the CLI runs in, when that folder is the one recorded, and says so on stderr; never a campaign. docs/projects.md is the contract.
• CLI: prints the exact API response as compact JSON on stdout by default, --human renders for people, stderr is diagnostics only. Exit codes: 0 success, 1 understood and refused (an API business error, or a local act the CLI refused to perform), 2 usage error, 3 runtime unreachable or unauthorized. The verb map is one-to-one with API operations with nine declared exceptions: jason status answers "can this installation start work?", half of which is not the runtime's to know, so no operation can stand behind it; jason uninstall takes this installation off the machine — a logon registration, an executable, a PATH entry, the files a deployment recorded — which the runtime neither performs nor is asked about; the skills and update nouns and the jason ui install and jason plugin install verbs change this installation's files — deploying skills, replacing the executable and redeploying the recorded skills, placing the release's UI as the default build, placing a plugin package the release publishes — rather than ask the runtime anything (each is the one such verb under a noun whose other verbs are operations, plugin install asks only the reload plugin reload asks and never starts a runtime, and the verb-map tests hold the ui group to its three operations and install and the plugin group to its two and install); jason logs reads the installation's log files, which the runtime writes and is never asked about; jason session open starts the person's own agent host — the one the named preference agent.interactive_host names — in a new terminal window at the campaign's folder with the item's brief as its first input, a terminal being no runtime's to start or know about, so the runtime is asked only what approval get --prompt and decision get --prompt ask and preference.list, and Jason's brief asks the agent to propose only and not to approve, reject or answer; what it may run is the host's own permission settings' to decide (the verb-map tests hold the session noun to open alone); and jason doctor collects one installation into one file, half of which is not the runtime's to know — of the runtime it asks only what the runtime says about itself, its roles, profiles, routes and subscriptions, and the journal and work-item pages it counts, keeping their metadata and dropping their values. status, logs and doctor exit 0 or 1 and never 3 — logs never asks the runtime, and for the other two "I could not ask the runtime" is an answer rather than a reason there is none — and the body of status carries ready so an agent branches on the body, never on the code. uninstall removes skills only by receipt and the rest of the installation by rule, and keeps the data directory unless --purge-data says otherwise. doctor lists what it would write before it writes — --dry-run lists it and writes nothing — reaches no network and uploads nothing; only --include-journal adds what the journal entries say: campaign names and fields as they changed, project names as they changed, the folders a project link recorded, campaign and work-item contexts as they changed, result formats, the addresses and numbers put on or taken off the do-not-contact register, the accounts a campaign's routes bind, the options decisions were answered with, the errors attempts ended with, provider identifiers, the verdicts roles recorded on replies and the decisions whose answers they carry, and the standing approvals people set: their categories, reactions, goals and limits, the effect, tool and operation a report names, the failure text and receipts notification channels reported, entries people and agents wrote themselves, the names actors gave, and the reasons they typed — and it prints a warning; a plugin's configuration under Plugins:Config travels under no flag, withheld whole, keys and values; the runtime's own report (system_info) travels projected, withholding channel detail, presence detail outside the runtime's own words, skill problem text and the release-notes URL, and the bundle says so; and before anything is written the home directory becomes ~, a data directory other than ~/.jason <data> wherever it stands, a different one the runtime keeps its data in a mark of its own, the harness root <harness_root> wherever it stands, the executable's folder outside home <install_dir> unless a package manager's prefix holds it, the account's user, machine and domain names and SIDs marks of their own, every plugin id, role name and skill pack name Jason did not ship an alias per distinct name (<plugin-N>, <role-N>, <skill-pack-N>), and a skill source other than the public repository, with its ref unless that is a release tag, <skill-source>. CliApp states all nine where the rule is written, each verb's --help publishes its own contract — which checks are required, what is removed, what is never touched and what a bundle never carries — and guards hold the list to these nine.
• Persistence: EF Core over SQLite in WAL mode, snake_case tables and columns, integer primary keys plus a unique public ULID. The journal table is append-only, enforced three times over: no API path that changes an entry, an EF interceptor, and database triggers. Schema-less JSON — campaign context, contact custom fields, channel data — is stored as JSON text through a converter, and channels live in contact_channels. Migrations apply automatically on runtime start after a pre-migration backup; a migration that fails puts that backup back and the start fails saying so, and older backups are pruned only after a migration has succeeded. Never edit a migration after it has been committed; raw SQL such as the journal triggers is added to a new migration when it is created. work_items.result_json is frozen by a trigger once the item is finished; a filtered unique index allows one live attempt per item.
• Configuration: strongly typed options only; user overrides in ~/.jason/config/settings.json, environment variables JASON_*; the data directory itself comes from JASON_DATA_DIR or defaults to ~/.jason, and the harness root from Harness:Root or defaults to ~/Jason — an absolute path, never the home directory, a folder holding it or the top of a drive, nor the data directory, a folder inside it or one holding it, read at every create and move; a test runtime is given a home of its own, so no test makes a folder in a real one. Settings are bound through IOptions<T> with validation on start; the dispatcher reads IOptionsMonitor<T> each tick, so edits to settings.json apply live except Dispatcher:MaxParallel, which sizes the handler pool when the runtime starts, and Dispatcher:Enabled, which decides at start whether this runtime has a dispatch loop at all. A live edit never stops the runtime: a refused edit keeps the last good settings and is logged by path and type, and a start with a malformed or mistyped file still fails, saying where — on stderr under jason runtime run, and after "It said:" in what jason runtime start answers: the line and byte of a malformed file, the setting's path and expected type for a mistyped one.
• Logs are JSON Lines under ~/.jason/logs/ and never contain request bodies, prompts, work-item contexts or the capability token: no text a person gives Jason — a context, a field, a brief, an operation's argument, a package's manifest, a refused setting, a reason — reaches them, held by a guard over every message template the runtime writes and by a run of the real executable that reads its own log back; the paths the installation runs from do, and a bundle rewrites them. jason logs reads them without the runtime; jason doctor carries a bounded slice of them.
• Everything in the repository is written in English.

Working style

• Test-driven: write the failing test, make it pass, commit small. Every behaviour arrives with its test.
• Feature branches; one squash-merged pull request per increment, described for an outside reader: what changed, why, how it was verified.
• Design notes, plans and scratch files do not belong in the repository.
• Commit messages and pull requests carry no ticket references, links to private systems, or tooling attribution trailers.