@zerwiz/ymir 0.1.4 → 0.1.5

package/RULES/06-append-only.md

@@ -0,0 +1,58 @@
+# Rule 06 — Append-only
+
+Some records are the system's memory. They are **appended to**, never rewritten,
+never truncated, never reordered — and **never lost in a move**.
+
+## What is append-only
+
+```
+append_only[6]{artifact,why}:
+  "$YMIR_HOME/memory/runes_audit.md","the Runes ledger — each entry folds the previous checksum, so a rewritten line breaks every later line"
+  "$YMIR_HOME/docs/append-only-log.md","the decision log: what was decided, when, and why"
+  "CHANGELOG.md","chronological entries; Brokk appends and never rewrites"
+  "RULES/*.md","house law: a rule that contradicts another is changed first, never silently edited"
+  "$YMIR_HOME/**","the private record — the operator's hoard, committed to the private git repo, never gitignored"
+  "*.jsonl / branch outcomes / session logs","event streams; a re-run is a new file, not a shorter one"
+```
+
+## The law
+
+- **Append, never rewrite.** A correction is a **new** entry that cites the old
+  one. The old text stays; that is what makes the record trustworthy.
+- **Never truncate.** Rotation is a new file with a new name, never a shortened
+  one. "It is long" is not a reason to delete a line.
+- **Never lose one in a move.** A migration, re-clone, swap or backup **must carry
+  every append-only artifact**. They are the part of the system that cannot be
+  regenerated from code.
+- **Never rewrite shared history to tidy it.** A force-push or history rewrite
+  must be weighed against this rule before it happens, not after.
+- **A contradiction changes the rule first.** The rules themselves obey this
+  rule: append the change, keep the history.
+- **Verify by name at the boundary.** Before and after any move, check the
+  append-only set explicitly — a move that drops one is a **violation**, not an
+  accident.
+
+## The duty at a move
+
+This rule exists because a home swap dropped `docs/append-only-log.md`,
+`docs/masterplan.md`, `docs/plans/` and the private business set: the backup
+carried `state`, `.env.local`, `data`, the realm and `workspace` — but not
+`docs/` or `assets/`. The code arrived; the memory did not.
+
+So the check is explicit, and it is part of the move:
+
+```bash
+# the append-only set must exist on both sides of a move
+for f in CHANGELOG.md docs/append-only-log.md; do
+  [ -e "$f" ] || echo "MISSING append-only artifact: $f"
+done
+# and the private set must be in YMIR_HOME, not merely in the old home
+ls "$YMIR_HOME/docs" "$YMIR_HOME/identity" "$YMIR_HOME/data" 2>/dev/null
+```
+
+A backup is only as good as its file list. If a directory is not named in the
+backup, it is not carried — and this rule says the append-only and private sets
+are always named.
+
+**Related:** `RULES/04-hoard.md` (where private records live), `AGENTS.md`,
+`.agents/skills/galdr-ymirsystem/assets/installation.md` (the move procedure).

package/RULES/07-config.md

@@ -0,0 +1,45 @@
+# Rule 07 — Configuration is never hardcoded
+
+Every port, host, endpoint, path, credential, and tunable is **configuration**, not
+a literal baked into shipped runtime. A hardcoded value is a bug that only appears
+on someone else's machine — or someone else's server.
+
+## The law
+
+- **One default, one place.** A value has exactly one documented default, owned by
+  the portability layer (`bin/ymir-platform.sh`) or a config file (e.g.
+  `config/agents.yaml`). Everywhere else reads it; nothing else restates it.
+- **Env first, then config, then the documented default.** Resolve as
+  `${VAR:-default}` (or the app's equivalent) — never a bare literal.
+- **No literal ports.** Ports come from env (`HLIDSKJALF_PORT`,
+  `HLIDSKJALF_API_PORT`, `SMIDJA_VIZ_API_PORT`, `PORT`, …). A published port, a
+  proxy target, and a health probe must all read the *same* source.
+- **No literal hosts or URLs.** `127.0.0.1`, `localhost`, tunnel hostnames, registry
+  and mesh endpoints resolve from env/config.
+- **No literal paths to secrets.** Secrets are referenced by path (`YMIR_HOARD`,
+  `.env.local`, `.env.realm`) and resolved at run time; never inlined.
+- **No literal credentials. Ever.**
+- **Bind and publish are separate and explicit.** An app binds a host
+  (`HLIDSKJALF_HOST`); a deployment publishes a host-IP/port. Neither assumes the
+  other's value.
+- **A deployment overrides; it never patches the core.** Environments run from
+  env/config (`deploy/env.example`, Quadlet/Compose env), so the same core runs
+  anywhere — a laptop, a bare box, a container, or a shared server.
+
+## Scope
+
+Every shipped surface: `bin/`, `scripts/`, `apps/`, `.agents/skills/**` tools,
+deploy manifests, and generated config.
+
+## Enforcement
+
+- Review, plus `bash .agents/skills/galdr-ymirsystem/scripts/compliance-check.sh`.
+- The portability layer is the **one** place that knows an environment difference
+  (Rule 05). A hardcoded value is a Rule 05 violation as well as a Rule 07 one.
+
+## Why
+
+Hardcoding is how a substrate written on one machine breaks on another, or
+collides with a neighbour's port on a shared server — the exact failure a
+host-agnostic core exists to prevent. This rule is the companion of Rule 05: Rule
+05 keeps *behaviour* portable; Rule 07 keeps *configuration* portable.

package/RULES/08-delivery-gate.md

@@ -0,0 +1,75 @@
+# Rule 08 — Delivery Gate & Worktree Engine
+
+## 08.1 Every Change Leaves by Pull Request
+
+**No direct pushes to `main` or any protected branch.** Every change — code,
+config, docs, scripts — must:
+
+1. Be done in a Yggdrasil worktree on a feature branch
+2. Pass all local gates (lint, typecheck, tests)
+3. Be pushed as a branch
+4. Opened as a Pull Request via `gh pr create`
+5. Reviewed in Glitnir (human review)
+6. Approved by the Allfather
+7. Merged via the PR interface — **never locally**
+
+A local merge on a verbal "word" is a decision, not a delivery. It leaves
+Glitnir with nothing to review. The gate is only fed by a PR.
+
+**Exception:** None. If work is already on local `main`, ship it as a PR (a
+branch at that commit) before doing anything else.
+
+## 08.2 Yggdrasil Worktrees Use treehouse
+
+**All worktree operations go through `treehouse`** (github.com/kunchenguid/treehouse).
+Never use raw `git worktree` commands directly.
+
+| Operation | Command |
+|-----------|---------|
+| Create worktree | `bin/yggdrasil.sh create <branch>` |
+| List worktrees | `bin/yggdrasil.sh list` |
+| Remove worktree | `bin/yggdrasil.sh remove <branch>` |
+| Sync worktree | `bin/yggdrasil.sh sync <branch>` |
+
+The `bin/yggdrasil.sh` script is the Norse shell over the treehouse engine.
+It handles:
+- Branch creation from correct base
+- Worktree path management under `.yggdrasil/<agent-id>/`
+- Remote tracking setup
+- Cleanup on completion
+
+## 08.3 Utgard Sandboxes Use sandcastle
+
+**All untrusted code, dynamic skills, and sub-agent tasks run inside Utgard**
+via `sandcastle` (github.com/mattpocock/sandcastle, @ai-hero/sandcastle).
+Never run untrusted code on the host.
+
+| Operation | Command |
+|-----------|---------|
+| Spawn sandbox | `bin/utgard.sh spawn <profile>` |
+| Run in sandbox | `bin/utgard.sh run <profile> <cmd>` |
+| Destroy sandbox | `bin/utgard.sh destroy <id>` |
+
+Utgard enforces: CPU/RAM/timeout caps, no host root, no network by default.
+A failed Utgard execution never touches main.
+
+## 08.4 Enforcement
+
+- **Pre-push hook** (installed by `bin/ymir-install.sh`) rejects direct pushes
+  to protected branches
+- **CI gate** (`.no-mistakes.yaml` + `no-mistakes` skill) validates PRs before
+  merge
+- **Mjollnir pipeline** (`bin/mjollnir.sh`) automates issue → worktree → PR
+
+## 08.5 References
+
+- `bin/yggdrasil.sh` — treehouse wrapper
+- `bin/utgard.sh` — sandcastle wrapper
+- `bin/mjollnir.sh` — issue→PR pipeline
+- `.no-mistakes.yaml` — clean-PR gate config
+- `RULES/02-agents.md` — agents are canonical, harness dirs are symlinks
+- `RULES/05-platforms.md` — core portable, per-OS layers updated together
+
+---
+
+*Append-only. A correction is a new entry citing the old one.*

package/RULES/README.md

@@ -0,0 +1,20 @@
+# RULES — the house law
+
+Numbered, binding rules for how Ymir is organised. A rule is law: code, plans,
+UI, and agents obey it, and a change that contradicts a rule must first change
+the rule (append-only; never silently rewritten).
+
+```
+rules_index[9]{file,subject}:
+  "01-domains.md","domains (Greinar) · houses · Eindri"
+  "02-agents.md","agents: home, kinds, profile contract, no mock"
+  "03-houses.md","houses = companies; ownership, records, boundaries"
+  "04-hoard.md","Hodd: the one private place — secrets, docs, tenants, identity"
+  "05-platforms.md","one portable core + per-OS installation layers; core changes propagate"
+  "06-append-only.md","some records are memory: append, never rewrite, never lose on a move"
+  "07-config.md","configuration is never hardcoded: ports/hosts/paths/credentials resolve from env/config"
+  "08-delivery-gate.md","PR-only delivery; treehouse worktrees; sandcastle sandboxes"
+  "README.md","this index"
+```
+
+Keep each rule short and unambiguous; reference it from code where it bites.

package/bin/README.md

@@ -0,0 +1,107 @@
+# `bin/` — what every file does
+
+Auto-generated from each script's header. One line per tool. Ported scripts are
+credited to the upstream `firstmate` distro (port record: `.agents/skills/galdr-ymirsystem/assets/porting-upstream-to-norse.md`); the rest are Ymir's own.
+
+bin[101]{file,does}:
+  "a2a-mcp.sh","a2a-mcp.sh — install/verify the two A2A MCP servers into the harnesses so"
+  "a2a-serve.py","a2a-serve.py — a real A2A 1.0 server (a2a-sdk) whose agent is a seated Eindri:"
+  "a2a-serve.sh","a2a-serve.sh — run the a2a-sdk A2A 1.0 server for a seated Eindri."
+  "a2a-talk.sh","a2a-talk.sh — list A2A agents and talk to one (bidirectional reply)."
+  "agent-run.sh","agent-run.sh — run one agent's errand through the harness the Allfather chose."
+  "agents-config.sh","agents-config.sh — one YAML for the Allfather's agent/harness/model combination."
+  "bifrost-bridge.sh","bifrost-bridge.sh — raise/lower the model bridge (Bifrost: the bridge between"
+  "bifrost-ingress.sh","bifrost-ingress.sh — raise/lower the ingress stack (Bifrost · Heimdall · Gjallarhorn)."
+  "brokk","brokk — the primary agent's CLI (Brokk, the bellows-smith)."
+  "brokk-classify-lib.sh","tests, declared-external-wait vocabulary, and the working/paused absorb"
+  "brokk-lease-lib.sh","brokk-lease-lib.sh - the per-task supervision lease contract (one owner)."
+  "brokk-lease.sh","brokk-lease.sh - claim, release, inspect, and sweep per-task supervision leases."
+  "brokk-lint.sh","brokk-lint.sh — the Brokk lint gate. Single owner of lint for CI and"
+  "brokk-send.sh","brokk-send.sh — send a one-line steer to a running Brokk/Eindri-home."
+  "brokk-update.sh","brokk-update.sh — update Brokk and every registered Eindri-home to the latest."
+  "brokk-wake-grant.sh","shellcheck source=bin/brokk-wake-lib.sh"
+  "brokk-wake-lib.sh","Shared durable wake queue and portable lock helpers."
+  "crash-sense.sh","A crash nobody sees is a crash nobody fixes. This watches systemd-coredump for"
+  "desktop-place.sh","desktop-place.sh — put the Ymir apps on their own Hyprland desktops."
+  "docs-guard.sh","docs-guard.sh — docs/ is the PUBLIC, user-facing tree. Block operator-private"
+  "editor-place.sh","editor-place.sh — the editor opens on its OWN desktop, never on yours."
+  "eindri-control.sh","eindri-control.sh — the CONTROL plane: allowlisted lifecycle verbs for a"
+  "eindri-role.sh","eindri-role.sh — the right smith for the right metal."
+  "eindri-send.sh","eindri-send.sh — the DATA plane: send conversational text to a seated Eindri."
+  "eindri-start.sh","eindri-start.sh — start an Eindri as the Allfather asks. One command."
+  "einherjar-spawn.sh","einherjar-spawn.sh - gather an Eindri worker (Einherjar = the chosen who are"
+  "erindi-brief.sh","erindi-brief.sh - scaffold an Eindri worker brief at data/<task-id>/brief.md."
+  "fleet-apply.sh","fleet-apply.sh — apply fleet-wide preferences to every registered Eindri-home."
+  "github-deploy.sh","github-deploy.sh — zero-trust deploys (W0035). Sync secrets from the local env"
+  "gjallarhorn-notify.sh","gjallarhorn-notify.sh — the horn (W0036). Unified push: Telegram + a web/WS"
+  "gjallarhorn-purge.sh","gjallarhorn-purge.sh — purge the Cloudflare edge cache for a hostname."
+  "gjallarhorn-tunnel.sh","gjallarhorn-tunnel.sh — raise/lower the `ymir` Cloudflare tunnel (Gjallarhorn)."
+  "gleipnir-lock-lib.sh","gleipnir-lock-lib.sh - per-home session lock for the Brokk runtime."
+  "hamr-harness.sh","hamr-harness.sh - detect the agent harness (Hamr) this process tree runs on."
+  "heimdall-ssh-keys.sh","heimdall-ssh-keys.sh — Heimdall's SSH-keys surface."
+  "herdr-agents.py","(no header description)"
+  "herdr-ensure.sh","herdr-ensure.sh — Þjazi: guarantee the terminal backend Ymir needs."
+  "herdr-run.sh","herdr-run.sh — raise an Eindri in herdr, by the grain that fits the errand."
+  "hermes-ensure.sh","hermes-ensure.sh — ensure the Hermes agent runtime is present."
+  "hodd.sh","hodd.sh — the Allfather's private hoard: path, init, ls, load, tenant."
+  "local-model-lock.sh","local-model-lock.sh — serialize LOCAL model inference on one machine."
+  "mimir-bridge.py","(no header description)"
+  "mimir-bridge.sh","mimir-bridge.sh — raise/lower the well bridge (Mimirsbrunn on :4602)."
+  "mimir-ingest.sh","mimir-ingest.sh — ingest the repo's data material into the well (Mimirsbrunn)."
+  "mimir.sh","mimir.sh — the well (Mimirsbrunn). Drink before you act, water it after."
+  "mjollnir-webhook.sh","mjollnir-webhook.sh — HMAC-verified GitHub webhook → Mjollnir (W0018)."
+  "mjollnir.sh","mjollnir.sh — the hammer (W0018). An issue becomes a PR: read the issue, cut a"
+  "model-resolve.sh","model-resolve.sh — resolve a human model request to a concrete harness+model."
+  "nornir-cron-start.sh","nornir-cron-start.sh - ensure Brokk's scheduled jobs are running (idempotent)."
+  "nornir-job-daily-briefing.sh","nornir-job-daily-briefing.sh - the 07:00 Sága daily seeing."
+  "nornir-job-git-sync.sh","nornir-job-git-sync.sh - Yggdrasil, the world-tree kept in order."
+  "nornir-job-memory-housekeeping.sh","nornir-job-memory-housekeeping.sh - Muninn, the raven of memory."
+  "nornir-job-observer.sh","nornir-job-observer.sh - Huginn, the raven of observation."
+  "omarchy-hook-install.sh","omarchy-hook-install.sh — let Ymir notice when Omarchy updates."
+  "omarchy-install.sh","omarchy-install.sh — the Omarchy installation layer (Rule 05)."
+  "omarchy-plugins.sh","omarchy-plugins.sh — the Omarchy plugins Ymir suggests, and installs on consent."
+  "omarchy-sense.sh","omarchy-sense.sh — learn the Allfather's Omarchy machine."
+  "perm-guard.sh","perm-guard.sh — flag agent profiles whose permissions are self-defeating."
+  "pi-agent.sh","pi-agent.sh — run a Ymir agent on a LOCAL model with ITS OWN persona/mission"
+  "pi-local.sh","pi-local.sh — run a Pi agent on a LOCAL model, reusable."
+  "pi-seat.sh","pi-seat.sh — seat a Pi agent in a VISIBLE herdr pane, optionally on a local"
+  "prereq-ensure.sh","prereq-ensure.sh — self-healing prerequisite engine for Ymir."
+  "private-guard.sh","private-guard.sh — enforce the Hoard boundary (Rule 04). Nothing under a"
+  "project-git.sh","project-git.sh — resolve a project's GitHub block from the master registry"
+  "public-guard.sh","public-guard.sh — every PUBLIC, user-facing file must be free of operator"
+  "ratatoskr.sh","ratatoskr.sh — Ymir's front door to the A2A engine (`a2abridge`)."
+  "repo-scrub.sh","repo-scrub.sh — purge private paths from ALL git history before going public."
+  "rodd-operational-input.sh","rodd-operational-input.sh - canonical Rödd operational-input protocol."
+  "runes-append.sh","runes-append.sh - append-only Runes audit ledger."
+  "saga-session-start.sh","saga-session-start.sh - the one-command Brokk session start."
+  "saga-sessionstart-run.sh","saga-sessionstart-run.sh - session-open entry point for run-tier harnesses."
+  "saga-wake-drain.sh","saga-wake-drain.sh - present durable Brokk wakes."
+  "secret-guard.sh","secret-guard.sh — refuse to commit obvious secrets or private env files."
+  "skuld-branch-outcome.sh","skuld-branch-outcome.sh - the durable outcome store for the Pi supervision"
+  "skuld-branch-prompt.sh","skuld-branch-prompt.sh - emit the supervision branch's system prompt"
+  "smidja-bootstrap.sh","smidja-bootstrap.sh — make the Smíðja visualizer ready on a fresh install."
+  "smidja-observe.sh","smidja-observe.sh — the smithy's trace, read-only (W0075). Reads the REPO's own"
+  "syn-arm-pretool-check.sh","syn-arm-pretool-check.sh - PreToolUse seatbelt for watcher-arm bash commands."
+  "syn-asset-pretool-check.sh","syn-asset-pretool-check.sh — PreToolUse seatbelt for governed paths."
+  "syn-cd-pretool-check.sh","syn-cd-pretool-check.sh - PreToolUse seatbelt for directory-changing commands."
+  "syn-guard-pretool-check.sh","syn-guard-pretool-check.sh — PreToolUse seatbelt for the runtime's load-bearing invariants."
+  "syn-turnend-guard.sh","syn-turnend-guard.sh - refuse to let a Brokk turn end blind."
+  "syn-watch-arm.sh","syn-watch-arm.sh - arm one Brokk supervision watcher cycle."
+  "tailscale-sync.sh","tailscale-sync.sh — sync the Allfather's pi data across his OWN machines over"
+  "telegram-bot.sh","telegram-bot.sh — the horn answers (W0036). Long-poll Telegram for the owner's"
+  "toolchain.sh","toolchain.sh — the provider wrappers (W0033). A typed front door to the tools"
+  "utgard.sh","utgard.sh — the sealed execution barrier (Utgard, the realm outside the wall)."
+  "valhalla.sh","valhalla.sh — the process hall (Valhalla). List, inspect, revive, and read logs"
+  "valknut-load.sh","valknut-load.sh — Valknut, the knot that binds the repo distro into each tool's"
+  "vor-crew-state.sh","vor-crew-state.sh - deterministic read of an Eindri worker's CURRENT state."
+  "wedge-notify.sh","wedge-notify.sh — the Ymir wedge-alarm notifier."
+  "workspace-provision.sh","workspace-provision.sh — carve one workspace for the operator. Single tenant:"
+  "workspace-rag.sh","workspace-rag.sh — memory over the realm workspaces (W0038)."
+  "wyrd-db.sh","wyrd-db.sh — the database layer (W0040). Applies the platform schema and reports"
+  "yggdrasil.sh","yggdrasil.sh — the worktree manager (Yggdrasil, the world-tree)."
+  "ymir-edit.sh","ymir-edit.sh — open a file in the Allfather's editor, on its own desktop."
+  "ymir-install.sh","ymir-install.sh — THE FIRST SETUP. Stand the full Ymir up for the operator:"
+  "ymir-migrate.sh","ymir-migrate.sh — versioned STRUCTURE migrations for existing Ymir homes."
+  "ymir-platform.sh","ymir-platform.sh — the portability layer."
+  "ymir-say.sh","ymir-say.sh — let Ymir speak on the Allfather's desktop."
+  "ymir-validate.sh","ymir-validate.sh — verify the installation actually works."

package/bin/a2a-mcp.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# a2a-mcp.sh — install/verify the Ymir MCP servers into the harnesses so every
+# agent can use the mesh, the memory well, and the control plane at once.
+#
+#   bin/a2a-mcp.sh install            # add a2abridge + engram (+wayofteams if present) to pi + opencode
+#   bin/a2a-mcp.sh install --project  # scoped: write the REPO's .pi/mcp.json + opencode.json, never ~/.pi
+#   bin/a2a-mcp.sh show [--project]   # what is wired, in the chosen scope
+#   bin/a2a-mcp.sh --version
+#
+# Scope: default writes Pi's GLOBAL MCP list (~/.pi/agent/mcp.json). `--project`
+# keeps everything inside the repo (`.pi/mcp.json` + `opencode.json`) so a Pi used
+# in other areas is left untouched — launch it with `pi --mcp-config .pi/mcp.json`
+# to pick the repo up.
+set -u
+
+VERSION="1.0.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+OC="$ROOT/opencode.json"
+A2AB="${A2ABRIDGE_BIN:-$HOME/.a2abridge/bin/a2abridge}"
+DIR="${A2A_DIRECTORY:-http://127.0.0.1:7777}"
+ADVERT="${A2A_ADVERTISE_HOST:-$(tailscale ip -4 2>/dev/null | head -1)}"
+[ -n "$ADVERT" ] || ADVERT="127.0.0.1"
+
+PROJECT=0; ACTION="show"
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --project) PROJECT=1 ;;
+    -v|-V|--version) printf '%s\n' "$VERSION"; exit 0 ;;
+    -h|--help) sed -n '2,12p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) ACTION="$1" ;;
+  esac
+  shift
+done
+if [ "$PROJECT" = 1 ]; then PI_MCP="$ROOT/.pi/mcp.json"; else PI_MCP="$HOME/.pi/agent/mcp.json"; fi
+
+WOTES="$(command -v wayofteams-mcp 2>/dev/null || true)"
+ENGRAM_BIN="${ENGRAM_BIN:-$HOME/.local/bin/engram-mcp}"
+YMIR_HOME="${YMIR_HOME:-$HOME/Documents/Ymir}"
+ENGRAM_DB="${ENGRAM_DB:-$YMIR_HOME/memory/kaia.engram}"
+
+python3 - "$ROOT" "$PI_MCP" "$OC" "$A2AB" "$DIR" "$ADVERT" "$WOTES" "$ACTION" "$ENGRAM_BIN" "$ENGRAM_DB" <<'PY'
+import sys, os, json
+root, pi_path, oc_path, a2ab, durl, advert, wotes, action, engram_bin, engram_db = sys.argv[1:11]
+
+def load(p, default):
+    try: return json.load(open(p))
+    except Exception: return default
+
+ones = {
+    "a2abridge": {
+        "pi":  {"command": a2ab, "args": ["bridge"],
+                "env": {"A2A_DIRECTORY": durl, "A2A_ADVERTISE_HOST": advert}},
+        "oc":  {"type": "local", "command": [a2ab, "bridge"],
+                "environment": {"A2A_DIRECTORY": durl, "A2A_ADVERTISE_HOST": advert}},
+    },
+    "engram": {
+        "pi":  {"command": engram_bin, "args": ["--db", engram_db]},
+        "oc":  {"type": "local", "command": [engram_bin, "--db", engram_db], "environment": {}},
+    },
+}
+if wotes:
+    ones["wayofteams"] = {
+        "pi":  {"command": wotes, "args": ["--stdio"], "env": {"WOTEAMS_URL": os.environ.get("WOTEAMS_URL","")}},
+        "oc":  {"type": "local", "command": [wotes, "--stdio"], "environment": {"WOTEAMS_URL": os.environ.get("WOTEAMS_URL","")}},
+    }
+
+if action == "show":
+    pi = load(pi_path, {}).get("mcpServers", {})
+    oc = load(oc_path, {}).get("mcp", {})
+    print(f"a2a-mcp[{len(ones)}]{{server,in_pi,in_opencode}}:")
+    for name in ones:
+        print(f'  "{name}","{"yes" if name in pi else "no"}","{"yes" if name in oc else "no"}"')
+    if not wotes:
+        print('help: wayofteams-mcp not on PATH — install it to enable the Teams plane')
+    sys.exit(0)
+
+if action != "install":
+    print("error: use install|show"); sys.exit(2)
+
+# pi mcp.json
+pid = load(pi_path, {"mcpServers": {}})
+pid.setdefault("mcpServers", {})
+for name, spec in ones.items():
+    pid["mcpServers"][name] = spec["pi"]
+os.makedirs(os.path.dirname(pi_path), exist_ok=True)
+json.dump(pid, open(pi_path, "w"), indent=2)
+
+# opencode.json mcp block
+ocd = load(oc_path, {"mcp": {}})
+ocd.setdefault("mcp", {})
+for name, spec in ones.items():
+    entry = spec["oc"]; entry["enabled"] = True
+    ocd["mcp"][name] = entry
+json.dump(ocd, open(oc_path, "w"), indent=2); open(oc_path, "a").write("\n")
+
+print(f'a2a-mcp[1]{{action,servers}}:\n  "install","{",".join(ones)}"')
+PY

package/bin/a2a-serve.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+# a2a-serve.py — a real A2A 1.0 server (a2a-sdk) whose agent is a seated Eindri:
+# it injects the task into the agent's chat via herdr and returns the reply.
+#
+#   a2a-serve.py <pane-or-agent> <name> <port>
+#
+# Replaces the hand-rolled server. Protocol/Agent Card/JSON-RPC are the SDK's;
+# our only job is the executor below.
+import asyncio
+import os
+import subprocess
+import sys
+import time
+
+import uvicorn
+from starlette.applications import Starlette
+
+from a2a.helpers import (
+    get_message_text,
+    new_task_from_user_message,
+    new_text_message,
+    new_text_part,
+)
+from a2a.server.agent_execution import AgentExecutor, RequestContext
+from a2a.server.events import EventQueue
+from a2a.server.request_handlers import DefaultRequestHandler
+from a2a.server.routes import create_agent_card_routes, create_jsonrpc_routes
+from a2a.server.tasks import InMemoryTaskStore, TaskUpdater
+from a2a.types import (
+    AgentCapabilities,
+    AgentCard,
+    AgentInterface,
+    AgentSkill,
+    TaskState,
+)
+
+TARGET = sys.argv[1]
+NAME = sys.argv[2]
+PORT = int(sys.argv[3])
+WAIT = float(os.environ.get("A2A_SERVE_WAIT", "30"))
+
+
+def sh(*a: str) -> str:
+    try:
+        return subprocess.run(a, capture_output=True, text=True, timeout=90).stdout
+    except Exception:
+        return ""
+
+
+def inject_and_read(text: str) -> str:
+    """Deliver the task into the seated agent's chat, then read its reply."""
+    sh("herdr", "agent", "prompt", TARGET, text)
+    time.sleep(WAIT)
+    out = sh("herdr", "agent", "read", TARGET).strip()
+    return "\n".join(out.splitlines()[-8:]) or "(no output)"
+
+
+class EindriExecutor(AgentExecutor):
+    async def execute(self, context: RequestContext, event_queue: EventQueue) -> None:
+        if context.current_task:
+            task = context.current_task
+        else:
+            task = new_task_from_user_message(context.message)
+            await event_queue.enqueue_event(task)
+        up = TaskUpdater(event_queue=event_queue, task_id=task.id, context_id=task.context_id)
+        await up.update_status(
+            state=TaskState.TASK_STATE_WORKING,
+            message=new_text_message("Delivering to the Eindri..."),
+        )
+        query = get_message_text(context.message) or ""
+        result = await asyncio.to_thread(inject_and_read, query)
+        await up.add_artifact(parts=[new_text_part(text=result, media_type="text/plain")])
+        await up.update_status(
+            state=TaskState.TASK_STATE_COMPLETED,
+            message=new_text_message(result),
+        )
+
+    async def cancel(self, context: RequestContext, event_queue: EventQueue) -> None:
+        raise NotImplementedError("Cancel is not supported.")
+
+
+skill = AgentSkill(
+    id="eindri", name=NAME, description=f"Ymir Eindri {NAME}",
+    input_modes=["text/plain"], output_modes=["text/plain"], tags=["ymir", "eindri"],
+)
+card = AgentCard(
+    name=NAME, description=f"Ymir Eindri {NAME}", version="1.0.0",
+    default_input_modes=["text/plain"], default_output_modes=["text/plain"],
+    capabilities=AgentCapabilities(streaming=False),
+    supported_interfaces=[AgentInterface(
+        protocol_binding="JSONRPC", url=f"http://127.0.0.1:{PORT}", protocol_version="1.0")],
+    skills=[skill],
+)
+handler = DefaultRequestHandler(
+    agent_executor=EindriExecutor(), task_store=InMemoryTaskStore(), agent_card=card,
+)
+routes: list = []
+routes.extend(create_agent_card_routes(card))
+routes.extend(create_jsonrpc_routes(handler, "/"))
+
+if __name__ == "__main__":
+    print(f"a2a-serve: {NAME} -> {TARGET} on http://127.0.0.1:{PORT}/", flush=True)
+    uvicorn.run(Starlette(routes=routes), host="127.0.0.1", port=PORT, log_level="warning")

package/bin/a2a-serve.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+# a2a-serve.sh — run the a2a-sdk A2A 1.0 server for a seated Eindri.
+#   bin/a2a-serve.sh <pane-or-agent> <name> [port]
+# The server is bin/a2a-serve.py (a2a-sdk); the executor injects via herdr.
+set -u
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PORT="${3:-7791}"
+exec python3 "$SCRIPT_DIR/a2a-serve.py" "$1" "${2:-eindri}" "$PORT"

package/bin/a2a-talk.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# a2a-talk.sh — list A2A agents and talk to one (bidirectional reply).
+#
+#   bin/a2a-talk.sh agents                 # who is registered
+#   bin/a2a-talk.sh send <peer> "<text>"   # send a task, print the reply
+#
+# Peer is matched by name (exact or prefix). Directory from A2A_DIRECTORY
+# (default http://127.0.0.1:7777). This is the proof-of-channel; pi gets the
+# same as a tool once the extension execute-API is wired.
+set -u
+DIR="${A2A_DIRECTORY:-http://127.0.0.1:7777}"
+ACTION="${1:-agents}"; shift || true
+
+agents_json() { curl -s --max-time 6 "$DIR/" 2>/dev/null; }
+
+case "$ACTION" in
+  agents)
+    agents_json | python3 -c 'import json,sys
+try:
+    d=json.load(sys.stdin); ags=d.get("served_agents",[])
+    print("a2a-agents[%d]{name,url,local}:" % len(ags))
+    for a in ags:
+        print("  \"%s\",\"%s\",\"%s\"" % (a.get("name"), a.get("url"), str(bool(a.get("local"))).lower()))
+except Exception:
+    print("error: directory unreachable")' ;;
+  send)
+    PEER="${1:-}"; shift || true; TEXT="${*:-}"
+    [ -n "$PEER" ] && [ -n "$TEXT" ] || { printf 'error: send <peer> "<text>"\n' >&2; exit 2; }
+    URL="$(agents_json | python3 -c 'import json,sys
+peer=sys.argv[1]
+try:
+    d=json.load(sys.stdin)
+    for a in d.get("served_agents",[]):
+        if a.get("name")==peer or (a.get("name") or "").startswith(peer):
+            print(a.get("url")); break
+except Exception: pass' "$PEER")"
+    [ -n "$URL" ] || { printf 'error: no peer matching "%s"\nhelp: bin/a2a-talk.sh agents\n' "$PEER" >&2; exit 1; }
+    curl -s --max-time 90 -X POST "$URL" -H 'Content-Type: application/json' \
+      -d "$(python3 -c 'import json,sys;print(json.dumps({"jsonrpc":"2.0","id":1,"method":"message/send","params":{"message":{"role":"user","parts":[{"kind":"text","text":sys.argv[1]}]}}}))' "$TEXT")" \
+      | python3 -c 'import json,sys
+try:
+    d=json.load(sys.stdin); r=d.get("result",{}); st=r.get("status",{})
+    parts=(st.get("message") or {}).get("parts",[])
+    text="\n".join(p.get("text","") for p in parts)
+    print("a2a-talk[1]{peer,state,reply}:")
+    print("  \"%s\",\"%s\",\"%s\"" % (sys.argv[1], st.get("state","?"), text))
+except Exception as e:
+    print("error: no reply:", e)' "$PEER" ;;
+  *) printf 'error: usage: bin/a2a-talk.sh agents|<send peer text>\n' >&2; exit 2 ;;
+esac