Jason Stedwell
791 lines
34 KiB
Python
791 lines
34 KiB
Python
#!/usr/bin/env python3
|
|
"""echo.py — the single validated, cross-platform client for the ECHO Obsidian
|
|
Local REST API.
|
|
|
|
Replaces the original echo.sh so the toolchain runs identically on Windows,
|
|
macOS, and Linux with no bash / GNU-vs-BSD `date` dependency — only a Python 3
|
|
interpreter (which the linter already requires).
|
|
|
|
Every read/write to the vault should go through this script. It centralizes:
|
|
auth injection, HTTP-status checking (non-zero exit on >=400 so a failed write
|
|
can never look like success), one bounded retry on 5xx/connection errors,
|
|
WHOLE-LINE idempotent append (a new line that is merely a substring of an
|
|
existing one is no longer wrongly skipped), correct `::` heading-target handling,
|
|
frontmatter field patches, a read-back-confirmed advisory multi-writer lock, a
|
|
one-call cold-start `load`, and scope show/set.
|
|
|
|
Network is keep-alive and connection-pooled (one persistent connection per thread,
|
|
reused across requests), and `read_many` fans bulk GETs across a thread pool — so
|
|
full-vault scripts (sweep, lint, recall rebuild) make a handful of warm round-trips
|
|
instead of hundreds of fresh TLS handshakes, and no longer blow past tool timeouts.
|
|
|
|
Config (owner/endpoint/key are machine-local — see echo_config; the plugin ships none):
|
|
owner/endpoint/key resolved by echo_config from ~/.claude/echo-memory/config.json
|
|
(env ECHO_OWNER / ECHO_BASE / ECHO_KEY override per field).
|
|
Set up a machine with `echo.py config init` then edit, or
|
|
`echo.py config set --owner ... --endpoint ... --key ...`.
|
|
ECHO_VERIFY default 1 — read-back verify after a PUT
|
|
ECHO_LOCK_TTL default 900 — seconds before an advisory lock is considered stale
|
|
ECHO_TIMEOUT default 30 — per-request socket timeout (seconds)
|
|
ECHO_WORKERS default 8 — concurrency for read_many bulk reads
|
|
ECHO_TODAY YYYY-MM-DD to use as "today" (pass the conversation's currentDate)
|
|
|
|
Usage:
|
|
echo.py load # cold-start: the 6 orientation reads in one call
|
|
echo.py get <path> # print file contents (404 -> exit 44)
|
|
echo.py map <path> # document-map JSON (headings/blocks/frontmatter)
|
|
echo.py ls <dir> # directory listing JSON
|
|
echo.py search <query...> # /search/simple
|
|
echo.py put <path> [file] # create/overwrite (body from file or stdin)
|
|
echo.py post <path> [file] # raw append (NON-idempotent; prefer `append`)
|
|
echo.py append <path> <line> # idempotent append: skips only on an exact whole-line match
|
|
echo.py patch <path> <append|prepend|replace> <heading|frontmatter|block> <target> [file]
|
|
echo.py fm <path> <field> <json-value> # PATCH a frontmatter scalar
|
|
echo.py bump <path> [YYYY-MM-DD] # set frontmatter updated: to today (or given date)
|
|
echo.py delete <path> # DELETE (destructive; explicit use only)
|
|
echo.py lock <owner-id> # acquire advisory lock (exit 75 if held & fresh, or lost the race)
|
|
echo.py unlock <owner-id> # release advisory lock if owned by <owner-id>
|
|
echo.py scope show # print active scope, its freshness, and sessions-since
|
|
echo.py scope set "<text>" # switch scope atomically (history + replace + stamp scope_updated)
|
|
echo.py config [show|init|set|import] # machine-local owner/endpoint/key (config import <file> adopts a provided file)
|
|
|
|
Exit codes: 0 ok · 44 not-found(404) · 75 lock-held/lost · 78 config-required · 2 usage · 1 other HTTP/transport error.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import argparse
|
|
import datetime as dt
|
|
import http.client
|
|
import json
|
|
import locale
|
|
import os
|
|
import sys
|
|
import tempfile
|
|
import threading
|
|
import time
|
|
import urllib.parse
|
|
from concurrent.futures import ThreadPoolExecutor
|
|
from pathlib import Path
|
|
|
|
# Never let a non-ASCII byte (em-dash in our own output, or Unicode in a fetched
|
|
# note) raise UnicodeEncodeError on a legacy Windows console.
|
|
for _stream in (sys.stdout, sys.stderr):
|
|
try:
|
|
_stream.reconfigure(encoding="utf-8", errors="replace") # type: ignore[union-attr]
|
|
except Exception:
|
|
pass
|
|
|
|
# Owner / endpoint / key are machine-local and resolved by echo_config from
|
|
# ~/.claude/echo-memory/config.json (env ECHO_OWNER / ECHO_BASE / ECHO_KEY override).
|
|
# The plugin ships none of them; load() returns "" for anything unset so --help,
|
|
# `config`, and `doctor` stay usable. Network ops raise a clear error if endpoint/key
|
|
# are missing (see _require_endpoint / request).
|
|
sys.path.insert(0, str(Path(__file__).resolve().parent))
|
|
import echo_config # noqa: E402
|
|
_CFG = echo_config.load()
|
|
BASE = _CFG["endpoint"]
|
|
KEY = _CFG["key"]
|
|
OWNER = _CFG["owner"]
|
|
VERIFY = os.environ.get("ECHO_VERIFY", "1") != "0"
|
|
LOCK_TTL = int(os.environ.get("ECHO_LOCK_TTL", "900"))
|
|
# Per-request socket timeout. A single stuck file fails fast instead of stalling a
|
|
# full-vault pass; with read_many concurrency it only blocks one worker, not the run.
|
|
TIMEOUT = int(os.environ.get("ECHO_TIMEOUT", "30"))
|
|
# Concurrency for bulk reads (read_many). I/O-bound, so threads bypass the GIL fine.
|
|
MAX_WORKERS = max(1, int(os.environ.get("ECHO_WORKERS", "8")))
|
|
|
|
LOCK_PATH = "_agent/locks/vault.lock"
|
|
|
|
|
|
class EchoError(RuntimeError):
|
|
def __init__(self, message: str, code: int = 1) -> None:
|
|
super().__init__(message)
|
|
self.code = code
|
|
|
|
|
|
def today() -> str:
|
|
return os.environ.get("ECHO_TODAY") or dt.date.today().isoformat()
|
|
|
|
|
|
def now_iso() -> str:
|
|
return dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
|
|
|
|
|
|
def vault_url(path: str) -> str:
|
|
safe = "/".join(urllib.parse.quote(part) for part in path.split("/"))
|
|
if path.endswith("/") and not safe.endswith("/"):
|
|
safe += "/"
|
|
return f"{BASE}/vault/{safe}"
|
|
|
|
|
|
# --- persistent connection pool (keep-alive) ---------------------------------
|
|
# urllib.urlopen opened a fresh TCP+TLS connection per call; against a remote HTTPS
|
|
# endpoint the repeated handshake dominated, so a full-vault pass made hundreds of
|
|
# serial handshakes and blew past the tool/sandbox timeout. We keep ONE connection
|
|
# per thread (http.client is not thread-safe, so each thread — main + every pool
|
|
# worker — owns its own) and reuse it across requests. read_many fans out over a
|
|
# thread pool, so the pool's connections stay warm for the duration of a sweep.
|
|
_local = threading.local()
|
|
MAX_ATTEMPTS = 3
|
|
|
|
|
|
def _require_config() -> None:
|
|
"""Fail loudly (not with an opaque DNS/connection error) when this machine has no
|
|
usable key file yet — the most common fresh-install state. Also catches an
|
|
untouched `config init` template (placeholder endpoint/key)."""
|
|
if not echo_config.is_configured(_CFG):
|
|
raise EchoError(
|
|
"echo: NOT CONFIGURED — no usable ECHO key file on this machine. Ask the "
|
|
f"operator for their config (owner/endpoint/key) and install it at "
|
|
f"{echo_config.config_path()}: `echo.py config import <file>`, or "
|
|
"`echo.py config set --owner ... --endpoint ... --key ...` "
|
|
"(or set ECHO_BASE / ECHO_KEY).", 2)
|
|
|
|
|
|
def _new_connection() -> http.client.HTTPConnection:
|
|
parts = urllib.parse.urlsplit(BASE)
|
|
host = parts.hostname or parts.path
|
|
if parts.scheme == "http":
|
|
return http.client.HTTPConnection(host, parts.port or 80, timeout=TIMEOUT)
|
|
return http.client.HTTPSConnection(host, parts.port or 443, timeout=TIMEOUT)
|
|
|
|
|
|
def _connection() -> http.client.HTTPConnection:
|
|
conn = getattr(_local, "conn", None)
|
|
if conn is None:
|
|
conn = _new_connection()
|
|
_local.conn = conn
|
|
return conn
|
|
|
|
|
|
def _drop_connection() -> None:
|
|
conn = getattr(_local, "conn", None)
|
|
if conn is not None:
|
|
try:
|
|
conn.close()
|
|
except Exception:
|
|
pass
|
|
_local.conn = None
|
|
|
|
|
|
def request(method: str, url: str, data: bytes | None = None,
|
|
headers: dict[str, str] | None = None) -> tuple[int, bytes]:
|
|
"""Issue one request over this thread's reused connection. Returns (status, body);
|
|
status 0 == transport failure (echo_queue relies on this to trigger offline queueing).
|
|
Retries: a stale pooled connection reconnects immediately; 5xx and other transport
|
|
errors get one bounded sleep-retry, same as before."""
|
|
_require_config()
|
|
merged = {"Authorization": f"Bearer {KEY}", **(headers or {})}
|
|
parts = urllib.parse.urlsplit(url)
|
|
target = parts.path or "/"
|
|
if parts.query:
|
|
target += "?" + parts.query
|
|
last_status, last_body = 0, b""
|
|
for attempt in range(MAX_ATTEMPTS):
|
|
try:
|
|
conn = _connection()
|
|
conn.request(method, target, body=data, headers=merged)
|
|
resp = conn.getresponse()
|
|
body = resp.read() # drain fully so the connection can be reused
|
|
status = resp.status
|
|
if status >= 500 and attempt < MAX_ATTEMPTS - 1:
|
|
_drop_connection()
|
|
time.sleep(1)
|
|
continue
|
|
return status, body
|
|
except (http.client.RemoteDisconnected, http.client.BadStatusLine,
|
|
ConnectionResetError, BrokenPipeError) as exc:
|
|
# The server closed an idle keep-alive connection between requests.
|
|
# Expected, not a failure: reconnect and retry without backing off.
|
|
_drop_connection()
|
|
last_status, last_body = 0, str(exc).encode()
|
|
continue
|
|
except Exception as exc: # timeout, DNS, refused, TLS, ...
|
|
_drop_connection()
|
|
last_status, last_body = 0, str(exc).encode()
|
|
if attempt < MAX_ATTEMPTS - 1:
|
|
time.sleep(1)
|
|
continue
|
|
return last_status, last_body
|
|
|
|
|
|
def get_text(path: str) -> str | None:
|
|
"""GET a vault path -> decoded text, or None on 404/any error. Never raises, so a
|
|
single unreadable note can't abort a bulk pass (resilience for sweep/lint)."""
|
|
try:
|
|
status, body = request("GET", vault_url(path))
|
|
except Exception:
|
|
return None
|
|
return body.decode(errors="replace") if status == 200 else None
|
|
|
|
|
|
def read_many(paths) -> dict[str, str | None]:
|
|
"""Concurrently GET many vault paths -> {path: text_or_None}. The single biggest
|
|
win for full-vault scripts: it turns hundreds of serial round-trips into MAX_WORKERS
|
|
parallel ones over warm keep-alive connections. Resilient — a bad file maps to None."""
|
|
unique = list(dict.fromkeys(paths))
|
|
if not unique:
|
|
return {}
|
|
workers = min(MAX_WORKERS, len(unique))
|
|
with ThreadPoolExecutor(max_workers=workers) as pool:
|
|
return dict(zip(unique, pool.map(get_text, unique)))
|
|
|
|
|
|
def check(status: int, body: bytes, context: str) -> None:
|
|
if status == 404:
|
|
raise EchoError(f"{context}: not found", 44)
|
|
if status == 0:
|
|
raise EchoError(f"{context}: vault unreachable ({body.decode(errors='replace')}) [{BASE}]", 1)
|
|
if status >= 400:
|
|
raise EchoError(f"{context}: HTTP {status} - {body.decode(errors='replace')}", 1)
|
|
|
|
|
|
def read_body(arg: str | None) -> bytes:
|
|
if arg in (None, "-"):
|
|
raw = sys.stdin.buffer.read()
|
|
try:
|
|
text = raw.decode("utf-8")
|
|
except UnicodeDecodeError:
|
|
text = raw.decode(locale.getpreferredencoding(False) or "cp1252", errors="replace")
|
|
return text.encode("utf-8")
|
|
return Path(arg).read_bytes()
|
|
|
|
|
|
def normalize_patch_body(data: bytes, op: str, target_type: str) -> bytes:
|
|
"""Heading PATCH bodies need a leading newline on replace and a trailing
|
|
newline on append/prepend so the API does not concatenate onto adjacent text."""
|
|
if target_type != "heading":
|
|
return data
|
|
text = data.decode("utf-8", errors="replace")
|
|
if op == "replace":
|
|
text = text.strip("\r\n")
|
|
text = f"\n{text}\n" if text else "\n"
|
|
elif text and not text.endswith("\n"):
|
|
text += "\n"
|
|
return text.encode("utf-8")
|
|
|
|
|
|
def normalize_json_scalar(value: str) -> bytes:
|
|
"""Accept either a raw scalar ('Fabrication Lead') or pre-formed JSON ('"2026-06-20"')."""
|
|
value = value.strip()
|
|
try:
|
|
json.loads(value)
|
|
return value.encode("utf-8")
|
|
except json.JSONDecodeError:
|
|
return json.dumps(value).encode("utf-8")
|
|
|
|
|
|
def temp_file(data: bytes) -> str:
|
|
fh = tempfile.NamedTemporaryFile(delete=False)
|
|
try:
|
|
fh.write(data)
|
|
return fh.name
|
|
finally:
|
|
fh.close()
|
|
|
|
|
|
# ---- commands ----------------------------------------------------------------
|
|
|
|
def cmd_get(path: str) -> int:
|
|
status, body = request("GET", vault_url(path))
|
|
check(status, body, f"get {path}")
|
|
sys.stdout.buffer.write(body)
|
|
return 0
|
|
|
|
|
|
def cmd_map(path: str) -> int:
|
|
status, body = request("GET", vault_url(path),
|
|
headers={"Accept": "application/vnd.olrapi.document-map+json"})
|
|
check(status, body, f"map {path}")
|
|
sys.stdout.buffer.write(body)
|
|
return 0
|
|
|
|
|
|
def cmd_ls(path: str) -> int:
|
|
if not path.endswith("/"):
|
|
path += "/"
|
|
status, body = request("GET", vault_url(path))
|
|
check(status, body, f"ls {path}")
|
|
sys.stdout.buffer.write(body)
|
|
return 0
|
|
|
|
|
|
def cmd_search(query: list[str]) -> int:
|
|
q = urllib.parse.quote_plus(" ".join(query))
|
|
status, body = request("POST", f"{BASE}/search/simple/?query={q}")
|
|
check(status, body, "search")
|
|
sys.stdout.buffer.write(body)
|
|
return 0
|
|
|
|
|
|
def _qwrite(method: str, url: str, data: bytes | None = None, headers: dict | None = None):
|
|
"""A mutating request that survives an outage: routes through echo_queue.safe_request,
|
|
which enqueues the write and returns (202, ...) when the vault is unreachable (H2)."""
|
|
import echo_queue
|
|
return echo_queue.safe_request(method, url, data=data, headers=headers)
|
|
|
|
|
|
def cmd_put(path: str, file_arg: str | None) -> int:
|
|
data = read_body(file_arg)
|
|
status, body = _qwrite("PUT", vault_url(path), data=data,
|
|
headers={"Content-Type": "text/markdown"})
|
|
if status == 202:
|
|
print(f"queued (offline): PUT {path} — will sync on the next reachable session")
|
|
return 0
|
|
check(status, body, f"put {path}")
|
|
if VERIFY:
|
|
status, _ = request("GET", vault_url(path))
|
|
if status != 200:
|
|
raise EchoError(f"put {path}: write did not verify (GET returned {status})")
|
|
print(f"ok: PUT {path}")
|
|
return 0
|
|
|
|
|
|
def cmd_post(path: str, file_arg: str | None) -> int:
|
|
data = read_body(file_arg)
|
|
status, body = _qwrite("POST", vault_url(path), data=data,
|
|
headers={"Content-Type": "text/markdown"})
|
|
if status == 202:
|
|
print(f"queued (offline): POST {path} — will sync on the next reachable session")
|
|
return 0
|
|
check(status, body, f"post {path}")
|
|
print(f"ok: POST {path}")
|
|
return 0
|
|
|
|
|
|
def cmd_append(path: str, line: str) -> int:
|
|
"""Idempotent append. Skips ONLY when the exact whole line already exists —
|
|
a new line that is a substring of an existing one is still appended."""
|
|
status, body = request("GET", vault_url(path))
|
|
if status == 200:
|
|
existing = [ln.rstrip("\r") for ln in body.decode(errors="replace").splitlines()]
|
|
if line.rstrip("\r") in existing:
|
|
print(f"skip: line already present in {path}")
|
|
return 0
|
|
elif status == 0:
|
|
pass # offline: skip the idempotency read; queue the POST (flush dedups by content)
|
|
elif status != 404:
|
|
check(status, body, f"append(read) {path}")
|
|
status, body = _qwrite("POST", vault_url(path), data=f"{line}\n".encode(),
|
|
headers={"Content-Type": "text/markdown"})
|
|
if status == 202:
|
|
print(f"queued (offline): APPEND {path} — will sync on the next reachable session")
|
|
return 0
|
|
check(status, body, f"append {path}")
|
|
print(f"ok: APPEND {path}")
|
|
return 0
|
|
|
|
|
|
def cmd_patch(path: str, op: str, target_type: str, target: str, file_arg: str | None) -> int:
|
|
if op not in {"append", "prepend", "replace"}:
|
|
raise EchoError("patch: op must be append, prepend, or replace", 2)
|
|
if target_type not in {"heading", "frontmatter", "block"}:
|
|
raise EchoError("patch: target-type must be heading, frontmatter, or block", 2)
|
|
data = normalize_patch_body(read_body(file_arg), op, target_type)
|
|
status, body = _qwrite(
|
|
"PATCH",
|
|
vault_url(path),
|
|
data=data,
|
|
headers={
|
|
"Operation": op,
|
|
"Target-Type": target_type,
|
|
"Target": target,
|
|
"Content-Type": "application/json" if target_type == "frontmatter" else "text/markdown",
|
|
},
|
|
)
|
|
if status == 202:
|
|
print(f"queued (offline): PATCH {op} '{target}' -> {path} — will sync on the next reachable session")
|
|
return 0
|
|
check(status, body, f"patch {path} ({target})")
|
|
print(f"ok: PATCH {op} {target_type} '{target}' -> {path}")
|
|
return 0
|
|
|
|
|
|
def cmd_fm(path: str, field: str, value: str) -> int:
|
|
return cmd_patch(path, "replace", "frontmatter", field, temp_file(normalize_json_scalar(value)))
|
|
|
|
|
|
def cmd_delete(path: str) -> int:
|
|
status, body = _qwrite("DELETE", vault_url(path))
|
|
if status == 202:
|
|
print(f"queued (offline): DELETE {path} — will sync on the next reachable session")
|
|
return 0
|
|
check(status, body, f"delete {path}")
|
|
print(f"ok: DELETE {path}")
|
|
return 0
|
|
|
|
|
|
def parse_lock_time(value: str) -> int:
|
|
try:
|
|
return int(dt.datetime.strptime(value, "%Y-%m-%dT%H:%M:%SZ")
|
|
.replace(tzinfo=dt.timezone.utc).timestamp())
|
|
except Exception:
|
|
# Unparseable timestamp -> treat the lock as FRESH (return "now"), so a
|
|
# garbled lock is respected rather than silently stomped.
|
|
return int(time.time())
|
|
|
|
|
|
def cmd_lock(owner: str, quiet: bool = False) -> int:
|
|
status, body = request("GET", vault_url(LOCK_PATH))
|
|
if status == 200 and body.strip():
|
|
current = body.decode(errors="replace").strip()
|
|
held_owner, _, held_iso = current.partition(" @ ")
|
|
if held_owner != owner and int(time.time()) - parse_lock_time(held_iso) < LOCK_TTL:
|
|
print(f"lock held by '{held_owner}' since {held_iso} (fresh)", file=sys.stderr)
|
|
return 75
|
|
status, body = request("PUT", vault_url(LOCK_PATH), data=f"{owner} @ {now_iso()}\n".encode(),
|
|
headers={"Content-Type": "text/markdown"})
|
|
check(status, body, "lock")
|
|
# Read-back confirm we actually hold it. The REST API has no compare-and-swap,
|
|
# so two racers can both PUT; last writer wins. Whoever does not own the file
|
|
# on read-back backs off instead of proceeding under a false lock.
|
|
status, body = request("GET", vault_url(LOCK_PATH))
|
|
if status == 200:
|
|
held_owner = body.decode(errors="replace").split(" @ ", 1)[0].strip()
|
|
if held_owner != owner:
|
|
print(f"lock race: now held by '{held_owner}', not '{owner}' — backing off", file=sys.stderr)
|
|
return 75
|
|
if not quiet:
|
|
print(f"ok: locked by {owner}")
|
|
return 0
|
|
|
|
|
|
def cmd_unlock(owner: str, quiet: bool = False) -> int:
|
|
status, body = request("GET", vault_url(LOCK_PATH))
|
|
if status == 200:
|
|
held_owner = body.decode(errors="replace").split(" @ ", 1)[0].strip()
|
|
if held_owner != owner:
|
|
print(f"lock owned by '{held_owner}', not '{owner}' — not releasing", file=sys.stderr)
|
|
return 75
|
|
status, body = request("DELETE", vault_url(LOCK_PATH))
|
|
if status != 404:
|
|
check(status, body, "unlock")
|
|
if not quiet:
|
|
print("ok: unlocked")
|
|
return 0
|
|
|
|
|
|
def extract_heading(markdown: str, heading: str) -> str:
|
|
"""Return the body under a `## <heading>` up to the next `## ` heading."""
|
|
out: list[str] = []
|
|
capture = False
|
|
marker = f"## {heading}"
|
|
for line in markdown.splitlines():
|
|
if line.strip() == marker:
|
|
capture = True
|
|
continue
|
|
if capture and line.startswith("## "):
|
|
break
|
|
if capture:
|
|
out.append(line)
|
|
return "\n".join(out).strip()
|
|
|
|
|
|
def cmd_scope(subcommand: str, text: str | None = None) -> int:
|
|
path = "_agent/context/current-context.md"
|
|
status, body = request("GET", vault_url(path))
|
|
check(status, body, f"scope {subcommand}")
|
|
current = body.decode(errors="replace")
|
|
|
|
if subcommand == "show":
|
|
print("-- Active scope --")
|
|
print(extract_heading(current, "Scope"))
|
|
scope_updated = ""
|
|
for line in current.splitlines():
|
|
if line.startswith("scope_updated:"):
|
|
scope_updated = line.split(":", 1)[1].strip().strip('"').strip("'")
|
|
break
|
|
print(f"scope_updated: {scope_updated or '<missing — drift cannot be detected; run scope set or repair>'}")
|
|
# Count session logs dated after scope_updated (the drift signal).
|
|
if scope_updated:
|
|
status, body = request("GET", vault_url("_agent/sessions/"))
|
|
if status == 200:
|
|
try:
|
|
files = json.loads(body).get("files", [])
|
|
n = sum(1 for f in files if f.endswith(".md") and f[:10] > scope_updated)
|
|
print(f"sessions logged since: {n}")
|
|
except json.JSONDecodeError:
|
|
pass
|
|
return 0
|
|
|
|
if subcommand != "set":
|
|
raise EchoError("scope: use 'show' or 'set \"<text>\"'", 2)
|
|
if not text:
|
|
raise EchoError("scope set needs the new scope text", 2)
|
|
prior = extract_heading(current, "Scope").replace("\n", " ").strip()[:140] or "(prior scope)"
|
|
cmd_patch(path, "prepend", "heading", "Current Context::Scope History",
|
|
temp_file(f"- {today()}: {prior}\n".encode()))
|
|
cmd_patch(path, "replace", "heading", "Current Context::Scope",
|
|
temp_file(f"{text}\n".encode()))
|
|
try:
|
|
cmd_patch(path, "replace", "frontmatter", "scope_updated",
|
|
temp_file(json.dumps(today()).encode()))
|
|
except EchoError as exc:
|
|
raise EchoError(
|
|
"scope set: body switched, but scope_updated frontmatter is missing "
|
|
f"(run bootstrap.py to add it) [{exc}]"
|
|
)
|
|
print(f"ok: scope switched (prior archived to Scope History; scope_updated={today()})")
|
|
return 0
|
|
|
|
|
|
def cmd_load() -> int:
|
|
"""Cold-start orientation: the canonical 6 reads in one call. 404s on today's
|
|
daily note and the inbox are normal (printed as absent, not errors)."""
|
|
if not echo_config.is_configured(_CFG):
|
|
print("echo: NOT CONFIGURED — this machine has no usable ECHO key file yet.")
|
|
print(f"Expected at: {echo_config.config_path()}")
|
|
print("ACTION: ask the operator for their echo-memory config file (it holds the")
|
|
print(" vault owner, endpoint, and API key), then install it with ONE of:")
|
|
print(" python3 echo.py config import <path-to-their-file>")
|
|
print(" python3 echo.py config set --owner \"…\" --endpoint \"https://…\" --key \"…\"")
|
|
print("Then re-run load. (Memory is unavailable until configured.)")
|
|
return 78 # distinct: configuration required
|
|
targets = [
|
|
("marker", "_agent/echo-vault.md"),
|
|
("preferences", "_agent/memory/semantic/operator-preferences.md"),
|
|
("context", "_agent/context/current-context.md"),
|
|
("heartbeat", "_agent/heartbeat/last-session.md"),
|
|
("today", f"journal/daily/{today()}.md"),
|
|
("inbox", "inbox/captures/inbox.md"),
|
|
]
|
|
import echo_queue
|
|
# H2: sync any writes queued during a prior outage, best-effort and quiet on empty.
|
|
try:
|
|
synced = echo_queue.flush()
|
|
if synced:
|
|
print(f"(synced {synced} write(s) queued during a prior offline session)\n")
|
|
except Exception as exc: # noqa: BLE001 — never let queue upkeep block a load
|
|
print(f"(queue flush skipped: {exc})\n", file=sys.stderr)
|
|
|
|
marker_missing = False
|
|
heartbeat_absent = False
|
|
offline = False
|
|
for label, path in targets:
|
|
status, body = request("GET", vault_url(path))
|
|
if status == 200:
|
|
echo_queue.cache_put(path, body) # refresh last-known-good for offline fallback
|
|
print(f"===== {label}: {path} (HTTP 200) =====")
|
|
text = body.decode(errors="replace")
|
|
sys.stdout.write(text)
|
|
if not text.endswith("\n"):
|
|
sys.stdout.write("\n")
|
|
elif status == 404:
|
|
print(f"===== {label}: {path} (HTTP 404) =====")
|
|
print("(absent — fine)")
|
|
if label == "marker":
|
|
marker_missing = True
|
|
if label == "heartbeat":
|
|
heartbeat_absent = True
|
|
elif status == 0: # vault unreachable -> degrade to last-known-good cache
|
|
offline = True
|
|
cached = echo_queue.cache_get(path)
|
|
if cached is not None:
|
|
print(f"===== {label}: {path} (OFFLINE — serving stale cache) =====")
|
|
sys.stdout.write(cached.decode(errors="replace"))
|
|
if not cached.endswith(b"\n"):
|
|
sys.stdout.write("\n")
|
|
else:
|
|
print(f"===== {label}: {path} (OFFLINE — no cache) =====")
|
|
print("(unreachable and not cached)")
|
|
else:
|
|
print(f"===== {label}: {path} (HTTP {status}) =====")
|
|
print(f"(error HTTP {status}: {body.decode(errors='replace')[:200]})")
|
|
print()
|
|
# M3: heartbeat pointer missing/stale -> fall back to the recent sessions listing
|
|
# (matches the documented loading procedure) so orientation works without the pointer.
|
|
if heartbeat_absent and not offline:
|
|
st, body = request("GET", vault_url("_agent/sessions/"))
|
|
if st == 200:
|
|
try:
|
|
files = sorted((f for f in json.loads(body).get("files", []) if f.endswith(".md")),
|
|
reverse=True)
|
|
except json.JSONDecodeError:
|
|
files = []
|
|
if files:
|
|
print("===== recent sessions (heartbeat absent — fallback) =====")
|
|
for f in files[:5]:
|
|
print(f" _agent/sessions/{f}")
|
|
print()
|
|
if offline:
|
|
print("NOTE: vault unreachable — context above is last-known-good cache; writes this "
|
|
"session will be queued and synced when the vault returns.")
|
|
if marker_missing:
|
|
print("NOTE: marker absent — vault not bootstrapped. Run bootstrap.py before relying on memory.")
|
|
return 0
|
|
|
|
|
|
def cmd_config(args) -> int:
|
|
"""show | init | set the machine-local owner/endpoint/key config."""
|
|
path = echo_config.config_path()
|
|
if args.action == "init":
|
|
p, created = echo_config.init_template()
|
|
print(f"ok: wrote config template to {p} — edit it with your owner/endpoint/key"
|
|
if created else f"config already exists at {p} (left unchanged)")
|
|
return 0
|
|
if args.action == "import":
|
|
if not args.path:
|
|
print("config import: pass the path to a config file "
|
|
"(JSON with owner/endpoint/key)", file=sys.stderr)
|
|
return 2
|
|
try:
|
|
p = echo_config.import_file(args.path)
|
|
except RuntimeError as exc:
|
|
print(exc, file=sys.stderr)
|
|
return 2
|
|
print(f"ok: imported config to {p} (chmod 600 best-effort)")
|
|
return 0
|
|
if args.action == "set":
|
|
if args.owner is None and args.endpoint is None and args.key is None:
|
|
print("config set: pass at least one of --owner / --endpoint / --key", file=sys.stderr)
|
|
return 2
|
|
p = echo_config.write_config(args.owner, args.endpoint, args.key)
|
|
print(f"ok: updated {p} (chmod 600 best-effort)")
|
|
return 0
|
|
# show — never prints the key in the clear
|
|
cfg = echo_config.load()
|
|
key = cfg["key"]
|
|
redacted = (key[:4] + "…" + key[-4:]) if len(key) >= 12 else ("set" if key else "")
|
|
print(f"config file: {path}" + ("" if path.exists() else " (absent)"))
|
|
for field, shown in (("owner", cfg["owner"]), ("endpoint", cfg["endpoint"]), ("key", redacted)):
|
|
src = echo_config.source(field)
|
|
print(f" {field:9} {shown or '(unset)'} [{src}]")
|
|
return 0
|
|
|
|
|
|
def build_parser() -> argparse.ArgumentParser:
|
|
parser = argparse.ArgumentParser(description="Validated cross-platform ECHO vault client")
|
|
sub = parser.add_subparsers(dest="cmd", required=True)
|
|
sub.add_parser("load")
|
|
sub.add_parser("flush") # H2: replay writes queued during a prior outage
|
|
sub.add_parser("doctor") # M3: one-call readiness check
|
|
sub.add_parser("get").add_argument("path")
|
|
sub.add_parser("map").add_argument("path")
|
|
sub.add_parser("ls").add_argument("path")
|
|
sub.add_parser("search").add_argument("query", nargs="+")
|
|
p = sub.add_parser("put"); p.add_argument("path"); p.add_argument("file", nargs="?")
|
|
p = sub.add_parser("post"); p.add_argument("path"); p.add_argument("file", nargs="?")
|
|
p = sub.add_parser("append"); p.add_argument("path"); p.add_argument("line")
|
|
p = sub.add_parser("patch")
|
|
p.add_argument("path"); p.add_argument("op"); p.add_argument("target_type")
|
|
p.add_argument("target"); p.add_argument("file", nargs="?")
|
|
p = sub.add_parser("fm"); p.add_argument("path"); p.add_argument("field"); p.add_argument("value")
|
|
p = sub.add_parser("bump"); p.add_argument("path"); p.add_argument("date", nargs="?")
|
|
sub.add_parser("delete").add_argument("path")
|
|
sub.add_parser("lock").add_argument("owner")
|
|
sub.add_parser("unlock").add_argument("owner")
|
|
p = sub.add_parser("config") # machine-local owner/endpoint/key (see echo_config)
|
|
p.add_argument("action", nargs="?", default="show", choices=["show", "init", "set", "import"])
|
|
p.add_argument("path", nargs="?") # for `config import <path>`
|
|
p.add_argument("--owner"); p.add_argument("--endpoint"); p.add_argument("--key")
|
|
p = sub.add_parser("scope")
|
|
p.add_argument("subcommand", nargs="?", default="show", choices=["show", "set"])
|
|
p.add_argument("text", nargs="?")
|
|
p = sub.add_parser("reflect") # H5: apply a JSON proposal set (dry-run unless --apply)
|
|
p.add_argument("file", nargs="?")
|
|
p.add_argument("--apply", action="store_true")
|
|
|
|
# High-level operations (entity index + cross-links + recall). See echo_ops.py.
|
|
sub.add_parser("resolve").add_argument("mention", nargs="+")
|
|
p = sub.add_parser("recall"); p.add_argument("query", nargs="+"); p.add_argument("--limit", type=int, default=6)
|
|
p = sub.add_parser("link"); p.add_argument("a"); p.add_argument("b")
|
|
p = sub.add_parser("capture")
|
|
p.add_argument("title")
|
|
p.add_argument("file", nargs="?")
|
|
p.add_argument("--kind")
|
|
p.add_argument("--inbox", action="store_true")
|
|
p.add_argument("--status", default="")
|
|
p.add_argument("--aliases", default="")
|
|
p.add_argument("--source", default="")
|
|
p.add_argument("--date")
|
|
p.add_argument("--domain", default="business")
|
|
p.add_argument("--no-log", action="store_true")
|
|
p.add_argument("--json", action="store_true") # M4: emit a JSON result envelope
|
|
p.add_argument("--dry-run", action="store_true") # M4: preview the plan, write nothing
|
|
return parser
|
|
|
|
|
|
def main(argv: list[str] | None = None) -> int:
|
|
args = build_parser().parse_args(argv)
|
|
try:
|
|
if args.cmd == "load":
|
|
return cmd_load()
|
|
if args.cmd == "doctor":
|
|
import echo_doctor
|
|
return echo_doctor.run()
|
|
if args.cmd == "flush":
|
|
import echo_queue
|
|
n = echo_queue.flush()
|
|
remaining = len(echo_queue.pending())
|
|
if n:
|
|
print(f"ok: flushed {n} queued write(s)"
|
|
+ (f"; {remaining} still queued (vault unreachable)" if remaining else ""))
|
|
elif remaining:
|
|
print(f"ok: {remaining} write(s) still queued (vault unreachable)")
|
|
else:
|
|
print("ok: queue empty")
|
|
return 0
|
|
if args.cmd == "config":
|
|
return cmd_config(args)
|
|
if args.cmd == "get":
|
|
return cmd_get(args.path)
|
|
if args.cmd == "map":
|
|
return cmd_map(args.path)
|
|
if args.cmd == "ls":
|
|
return cmd_ls(args.path)
|
|
if args.cmd == "search":
|
|
return cmd_search(args.query)
|
|
if args.cmd == "put":
|
|
return cmd_put(args.path, args.file)
|
|
if args.cmd == "post":
|
|
return cmd_post(args.path, args.file)
|
|
if args.cmd == "append":
|
|
return cmd_append(args.path, args.line)
|
|
if args.cmd == "patch":
|
|
return cmd_patch(args.path, args.op, args.target_type, args.target, args.file)
|
|
if args.cmd == "fm":
|
|
return cmd_fm(args.path, args.field, args.value)
|
|
if args.cmd == "bump":
|
|
return cmd_fm(args.path, "updated", json.dumps(args.date or today()))
|
|
if args.cmd == "delete":
|
|
return cmd_delete(args.path)
|
|
if args.cmd == "lock":
|
|
return cmd_lock(args.owner)
|
|
if args.cmd == "unlock":
|
|
return cmd_unlock(args.owner)
|
|
if args.cmd == "scope":
|
|
return cmd_scope(args.subcommand, args.text)
|
|
if args.cmd == "reflect":
|
|
import echo_reflect
|
|
raw = read_body(args.file).decode("utf-8", errors="replace")
|
|
try:
|
|
proposals = json.loads(raw)
|
|
except json.JSONDecodeError as exc:
|
|
raise EchoError(f"reflect: proposals must be a JSON array ({exc})", 2)
|
|
if not isinstance(proposals, list):
|
|
raise EchoError("reflect: proposals must be a JSON array of objects", 2)
|
|
return echo_reflect.apply(proposals, confirm=args.apply)
|
|
if args.cmd in ("resolve", "recall", "link", "capture"):
|
|
import echo_ops # lazy: only the high-level ops pull in the index/link modules
|
|
if args.cmd == "resolve":
|
|
return echo_ops.resolve(" ".join(args.mention))
|
|
if args.cmd == "recall":
|
|
return echo_ops.recall(args.query, limit=args.limit)
|
|
if args.cmd == "link":
|
|
return echo_ops.link(args.a, args.b)
|
|
return echo_ops.capture(
|
|
args.kind, args.title, args.file, status_v=args.status,
|
|
aliases=args.aliases.split(",") if args.aliases else [],
|
|
sources=args.source.split(",") if args.source else [],
|
|
date=args.date, domain=args.domain, inbox=args.inbox, no_log=args.no_log,
|
|
as_json=args.json, dry_run=args.dry_run)
|
|
except EchoError as exc:
|
|
print(f"echo.py: {exc}", file=sys.stderr)
|
|
return exc.code
|
|
return 2
|
|
|
|
|
|
if __name__ == "__main__":
|
|
raise SystemExit(main())
|