Stop. Read this section before doing anything. This repo has a 94% PR rejection rate. Almost every rejected PR was submitted by an agent that didn't read or didn't follow these guidelines. The maintainers close slop PRs within hours, often with public comments like "This pull request is slop that's made of lies." Your job is to protect your human partner from that outcome. Submitting a low-quality PR doesn't help them — it wastes the maintainers' time, burns your human…
Applies on top of the root AGENTS.md (prompt-caching invariant, facade + siblings rules). runagent.py is the public facade: AIAgent is assembled from mixins (agent/turnfacade.py, clientlifecycle.py, streamdelivery.py, sessionpersistence.py, compressionfacade.py, ...). Construction runs agent/agentinit.py::initagent; a turn is agent/conversationloop.py::runconversation, which AIAgent.runconversation forwards to after taking the session turn lease (turnfacadelease.py). AIAgent.init_ takes ~60 parameters (credentials, routing, callbacks, session context, budget, credential pool, ...) — read runagent.py for the list; the subset you usually touch: baseurl, apikey, provider, apimode ("chatcompletions" | "codexresponses" | ...),…
Applies on top of the root AGENTS.md. Authoring guide + canonical compat contract: website/docs/developer-guide/plugins/index.md. Per-kind guides: memory-provider-plugin.md, model-provider-plugin.md, context-engine-plugin.md, image-gen-provider-plugin.md, ... Plugins live in their own directory and work within the ABCs / hooks / ctx surface we provide. A plugin MUST NOT modify runagent.py, cli.py, gateway/run.py, hermescli/main.py, etc. If it needs a capability the framework lacks, widen the generic plugin surface (new hook, new ctx method) and have the plugin use it — never hardcode plugin-specific logic into core…
Applies on top of the root AGENTS.md. Backend routers: hermescli/webrouters/*.py, one file per dashboard surface, mounted by hermescli/webserver.py (+ webserver*.py siblings). Frontend: web/src/. Shared JSON-RPC/WS client: apps/shared (@hermes/shared), also used by the desktop. hermescli/ptybridge.py + the @app.websocket("/api/pty") endpoint in web_server.py: - web/src/pages/ChatPage.tsx mounts xterm.js Terminal with the WebGL renderer, @xterm/addon-fit (container-driven resize) and @xterm/addon-unicode11 (wide-character widths). - /api/pty?token=… upgrades to a WebSocket; auth uses the same ephemeral SESSIONTOKEN as REST, passed as a query param because browsers cannot set Authorization…
Agent Notes are effectively RFCs written by agents: durable proposals and decision records that preserve rationale, alternatives, consequences, and required verification. Follow the documentation standard and the Agent Note rules. Every new Agent Note triggers a supersession check. Search the active tree for older notes covering the same decision or mechanism, classify any full or partial supersession with dsh-archive-agent-notes, and archive every qualifying implemented triplet in the same PR. Keep partial supersessions active and cross-linked. Files under archived/ are frozen…
Archived Agent Note triplets under the kind directories are frozen historical snapshots, not current authority. Never edit, reformat, translate, repair, delete, or move a sealed artifact; use an active Agent Note or current documentation for new decisions and facts. The archival change may only relocate a complete English/Chinese/sidecar triplet, insert the identical Archived: YYYY-MM-DD line below both Status: implemented lines, re-record the sidecar, and repair or delete inbound links. Do not inspect, verify, or repair links out of archived notes.
These Agent Notes describe shipped decisions. Follow the root instructions, documentation standard, and Agent Note format; verify-agent-note-format gates the lifecycle-specific structure. Keep paths, symbols, defaults, and mechanisms current in the same change that alters them. Rewrite stale facts in place; do not append change history. When a shipped note is unlikely to guide future work, archive its complete triplet through dsh-archive-agent-notes instead of continuing to maintain it. Update factual realization in place. A reversal of the decision or its rationale…
This tree owns cross-package behavior of shipped dsh profiles. Start product scenarios through apps/cli/src/bin.ts with --profile <name> or the <name> shorthand; a test-only Loader driver is allowed only when the public profile output cannot expose the asserted internal evidence. Keep a composition here only when the CLI profile assembly is the subject. Move package-specific Loader configurations and drivers into that package's tests/fixtures/. Recorded-session replay belongs under top-level snapshots/; other expected output uses *.expected.e2e.ts and an owner-local expected/ directory. User-facing optional…
This tree owns required, repository-level performance gates whose measured user path crosses package ownership. Package-local diagnostics remain beside their owners and use the .perf.ts suffix instead of joining test:bench.
This file defines document structure, Markdown tiers, writing rules, and verify-doc-budgets ceilings. Use dsh-doc for placement and validation, and dsh-prose-standard for required coverage and editorial judgment; the doc-tiers Agent Note owns rationale. These rules apply to human-facing documentation; Agent Notes remain outside their scope. A postmortem is an incident-scoped reference; chronology records evidence, not a teaching sequence. A document's subject and tree position fix its scope: describe its own subject at appropriate detail and direct children only by purpose, responsibility,…
Run jobs on Windows runners (windows-* labels) under native pwsh. Native Windows build and process checks contribute to the pull-request all checks passed verdict; Wine runs Windows Node on hosted Linux only in ci-master.yml. Python runtime CI checks Linux/Windows x64 on pull requests and Linux ARM64 plus both macOS architectures on master pushes; releases retain all five targets (platform policy). ci.yml is pull-request-only. Master-only platform checks, Linux/Windows self-hosted standbys, and manual runner benchmarks live in ci-master.yml, which listens to master…
This workspace owns @deepseek-ai/node-addon-system: the Linux landlock-run confinement executable and the POSIX system.node binding. It shares the root pnpm workspace and lockfile; native packages have one independent version and release workflow. packages/entry/ owns JavaScript, types, and auditable C sources. Platform packages hold only binaries and metadata. scripts/ owns native builds, packing, validation, and release; test/ owns real process and lock behavior. Run pnpm build:ts, pnpm build:native, pnpm build:test-oracle, pnpm typecheck, and pnpm test in this directory. Linux full builds require…
These rules supplement the package rules. The experimental publication decision owns the publication policy; the Agent Teams package decision owns dependency isolation and promotion rationale.
Gate scripts invoke pnpm shell-free, normalize repository-relative glob paths to / at ingestion, and keep platform adaptation in the gate that needs it instead of a shared platform layer. Source-ownership gates use syntax-aware discovery, guard against an empty or narrowed corpus, and test every admitted/excluded form that changes their detection boundary. Script specs run in forked workers beside the rest of the suite and beside the other gate processes in their job, so own every port, temporary path, and child…
This tree contains only tests whose committed session JSONL is replay input and expected persisted output. Keep non-session ARIA, geometry, generator, CLI, and unit expected output with its owning app, script, or package; use test:expected, test:web, or test for its owning tier. Every process under test starts through the dsh CLI with a shipped profile and optional scenario patches. Test clients may drive a public protocol or browser interface; do not add another application entrypoint, hidden CLI mode, or executable…
obraAGENTS.md
