waymark-hub 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Serj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+# Waymark
+
+[![CI](https://github.com/SerjMihashin/waymark/actions/workflows/ci.yml/badge.svg)](https://github.com/SerjMihashin/waymark/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+**Shared memory and handoff hub for AI agents.** A waymark is a trail sign left
+for whoever walks the path next — Waymark does the same for agent sessions:
+Claude Code finishes work, and the next session of Codex, Claude Desktop, or any
+other MCP client starts *already knowing* what was done, what was decided, and
+what to do next.
+
+No retelling. No re-reading the repo. One token-budgeted call.
+
+## Why
+
+Every new agent session starts cold: it re-reads files, re-asks questions, and
+burns tokens rediscovering context that another agent had five minutes ago.
+Waymark replaces that with a local MCP server over a single SQLite database
+shared by all your agents:
+
+- **`workspace_resume`** — one call returns a compact packet (project metadata,
+  open tasks, ranked memory, recent sessions, active handoff) within a token
+  budget you set (default 1,200 tokens).
+- **Automatic handoffs** — `session_log(outcome: "partial", next_steps: [...])`
+  writes a handoff memory that tops the next agent's resume. Logging
+  `completed` retires it. No discipline required.
+- **Task queue with atomic claims** — `task_claim` guarantees only one agent
+  takes a task, with capability and dependency checks.
+- **Memory lifecycle** — supersede instead of accumulate; feedback ratings
+  demote stale records in ranking.
+- **Provider-neutral** — agents register with provider/model/client identity;
+  nothing in the core is tied to one vendor.
+
+## Measured savings
+
+Continuation scenario (fresh session must orient in a project and name the next
+step), estimated cohort, reproducible via `node scripts/benchmark-orientation.cjs`:
+
+| | median tokens |
+|---|---|
+| Cold orientation (reading README, docs, sources, git log) | **13,540** |
+| Waymark resume (packet + core tool schemas + follow-up reads) | **3,392** |
+| **Net saving** | **74.9%** |
+
+The orientation context itself shrinks from ~13.1k tokens of raw files to a
+1.1k-token ranked packet (**−91.5%**) — and unlike cold reading, the packet
+contains what files can't: what the previous agent actually did and decided.
+The exact-token A/B protocol with live clients is in
+[docs/BENCHMARK_RUN.md](./docs/BENCHMARK_RUN.md).
+
+## Quick start
+
+Requires Node.js 22+.
+
+```bash
+npm install -g waymark-hub
+waymark-hub init          # registers the hub in Claude Code / Codex, offers the hook
+waymark-hub doctor        # verifies the whole installation
+```
+
+`init` asks before touching anything; `init --yes` enables everything
+applicable. The database lives in `~/.waymark/hub.db` (survives package
+upgrades); override with `WAYMARK_HOME` or `DB_PATH`.
+
+From source instead:
+
+```bash
+git clone https://github.com/SerjMihashin/waymark && cd waymark
+npm install && npm test   # build + 20 integration tests
+```
+
+### Connect Claude Code (stdio)
+
+`waymark-hub init --claude`, or manually:
+
+```bash
+claude mcp add --scope user waymark node "<install>/dist/server.js"
+```
+
+Optional but recommended — `waymark-hub init --hook` installs a `SessionStart`
+hook that injects the resume packet into every new session (zero tool calls
+spent on orientation).
+
+### Connect Codex
+
+`waymark-hub init --codex`, or manually:
+
+```toml
+# ~/.codex/config.toml
+[mcp_servers.waymark]
+command = "node"
+args = ["<install>/dist/server.js"]
+```
+
+### Connect Claude Desktop / web (HTTP)
+
+```bash
+waymark-hub serve --http   # listens on 127.0.0.1:3747
+```
+
+Add a custom connector: `http://localhost:3747/mcp`. Also available via
+`docker compose up -d` / `podman compose up -d`.
+
+## The protocol
+
+**Session start — one call, not three:**
+
+```
+workspace_resume(project_id, task?, agent_id?, max_tokens=1200)
+```
+
+**Session end:**
+
+```
+session_log(started_at, summary, outcome, next_steps?)   # partial/blocked → auto-handoff
+memory_write(...)                                        # only durable decisions/facts
+```
+
+**Cross-agent handoff** happens automatically: agent A logs a `partial` session
+with `next_steps`; agent B's `workspace_resume` surfaces that handoff first,
+with the session trail and files touched. When someone logs `completed`, the
+handoff retires itself.
+
+## Tool profiles
+
+Greedy MCP clients inject every tool schema into context each turn. Waymark
+defaults to a **core** profile of 10 tools (~1.8k tokens instead of ~4.7k for
+all 28). Set `HUB_TOOLS=full` where you need the admin surface (projects,
+agents, experiments, telemetry).
+
+## Tools (28)
+
+| Group | Tools |
+|---|---|
+| Context | `workspace_resume`, `context_get` |
+| Memory | `memory_write/read/list/search/set_status/feedback` |
+| Tasks | `task_create/list/update/claim/release/add_dependency` |
+| Projects | `project_list/get/upsert/set_status` |
+| Agents | `agent_register/get/list/set_status` |
+| Sessions & telemetry | `session_log`, `usage_report`, `experiment_create/list/update/summary` |
+
+Deep dives: [docs/CONTEXT.md](./docs/CONTEXT.md),
+[docs/MEMORY_LIFECYCLE.md](./docs/MEMORY_LIFECYCLE.md),
+[docs/TASK_COORDINATION.md](./docs/TASK_COORDINATION.md),
+[docs/BENCHMARKING.md](./docs/BENCHMARKING.md).
+
+## Dashboard
+
+`npm run dashboard` → read-only web panel on `http://localhost:4747`: projects,
+tasks, memory (FTS search), sessions, agents, benchmark results. Opens the DB
+in read-only mode — it physically cannot mutate hub state.
+
+## Architecture
+
+```
+src/server.ts            entry point: stdio / HTTP (--http), tool profiles
+src/db/client.ts         SQLite singleton (WAL) + idempotent migrations 001..005
+src/tools/               projects · memory · tasks · sessions · agents · context · telemetry
+src/context/builder.ts   deterministic ranking + token budget (no LLM calls)
+src/cli/benchmark.ts     A/B experiment CLI
+dashboard/               read-only Express panel
+```
+
+Storage: SQLite + FTS5. The core never calls an LLM or any external service.
+
+## Principles
+
+- **Context on demand** — summaries + ids by default; bodies only when asked.
+- **Budget first** — every aggregated response fits a token budget.
+- **Evidence over retelling** — link files/commits/tasks instead of copying text.
+- **Replace, don't accumulate** — supersede outdated memory, no duplicates.
+- **Provider-agnostic** — any MCP client is a first-class citizen.
+
+## License
+
+MIT

package/dashboard/README.md

@@ -0,0 +1,71 @@
+# Waymark — Dashboard
+
+Веб-панель хаба: тропа передач между агентами, доска задач, память с поиском,
+журнал сессий, агенты, бенчмарки. Живое обновление — панель следит за
+изменениями БД и перерисовывается сама.
+
+## Запуск
+
+```powershell
+npm run dashboard
+# → http://127.0.0.1:4747
+```
+
+Слушает только loopback (`127.0.0.1`). Настройки через переменные окружения:
+
+- `DASH_PORT` — порт (по умолчанию `4747`).
+- `DB_PATH` — путь к базе (по умолчанию `../data/hub.db` относительно этой папки,
+  то есть та же база, что у хаба).
+- `WAYMARK_ADMIN=1` — включить admin-режим (см. ниже).
+
+## Вкладки
+
+- **Обзор** — счётчики, задачи по статусам, активные передачи.
+- **Тропа** — фирменный вид: маршрут сессий проекта в хронологии. Оранжевый
+  ромб — «blaze», метка передачи: агент оставил эстафету (`session_log` с
+  outcome partial/blocked). Активная эстафета закреплена сверху — это то, что
+  следующий агент увидит первым в `workspace_resume`.
+- **Задачи** — доска по статусам (очередь → в работе → готово → отменено).
+- **Память** — фильтры по типу и статусу, поиск, важность/уверенность,
+  раскрытие тел по клику.
+- **Сессии / Агенты / Бенчмарки** — журнал работы, команда, A/B-эксперименты.
+
+## Режимы: read-only и admin
+
+**По умолчанию — только чтение.** База открывается в режиме `readonly`,
+панель физически не может изменить состояние, на которое полагаются агенты.
+
+**`WAYMARK_ADMIN=1`** добавляет точечные действия: перевод задач по статусам и
+архивирование записей памяти. Записи идут **через MCP-инструменты самого хаба**
+(in-process клиент → `task_update`, `memory_set_status`), а не сырым SQL — вся
+логика хаба (completed_at, FTS, валидация статусов) сохраняется. Без переменной
+окружения admin-эндпоинты отвечают 403.
+
+```powershell
+$env:WAYMARK_ADMIN='1'; npm run dashboard
+```
+
+## Перевод на русский (опционально)
+
+Кнопка **RU** в шапке включает машинный перевод содержимого (описания, сводки
+сессий, тела памяти) на русский. Подписи интерфейса и так русские — переводится
+только то, что агенты записали по-английски.
+
+⚠️ **Приватность.** Перевод выполняется через DeepSeek API, то есть выбранный
+текст хаба **отправляется на внешний сервер** `api.deepseek.com`. Панель
+предупредит и спросит согласие при первом включении. Ключ берётся из
+`DEEPSEEK_API_KEY` или `~/.deepseek-code/settings.json` и **остаётся на
+сервере** (в браузер не передаётся). Каждый уникальный текст переводится один
+раз и кешируется в `dashboard/.cache/` (в git не попадает). Тела памяти
+переводятся лениво — только при раскрытии.
+
+## Как устроено
+
+- `server.mjs` — Express-сервер: JSON API (`/api/*`) поверх `hub.db` через
+  read-only `better-sqlite3`; `/api/stats` отдаёт `data_version` для живого
+  обновления; admin-режим поднимает in-process MCP-клиент к хабу. Никаких новых
+  зависимостей — переиспользует `express` и `better-sqlite3` самого хаба.
+- `index.html` — одностраничный UI (vanilla JS + Tailwind), палитра «карта
+  ночью»: чернильный фон, сигнальный blaze-оранжевый для передач.
+- `vendor/tailwind.js` — Tailwind, заверстан локально (без внешнего CDN):
+  работает офлайн, нет риска компрометации CDN.