agent-bios 0.9.3 → 0.9.5

package/scripts/ingest-learnings-export.py

@@ -0,0 +1,258 @@
+#!/usr/bin/env python3
+"""Curation intake — map a dashboard learnings export to ledger candidates.
+
+Phase 3 of the collection loop (design/collection-loop/PHASE3-CURATION-DESIGN.md).
+The curator exports RECEIVED learnings from the dashboard as ledger-compatible
+JSON (GET /api/exports/learnings — verbatim payloads + provenance); THIS script
+does the DETERMINISTIC half of intake:
+
+  * validates each exported record against config/learning.schema.json — the
+    single validation source, reused from scripts/check-learning.py (no second
+    schema), so an invalid/verbatim-but-nonconforming payload is caught here;
+  * buckets each row: VALID → a ledger-candidate entry; REJECTED → schema or
+    domain-membership failure (with the reasons); DEFERRED → schema_version != 1
+    (Phase 2 stores v2+ verbatim for forward-compat; the v1 intake cannot map it
+    yet — it is NOT a reject, it is re-exportable once a v2-aware intake lands);
+  * flags candidates whose learning_id already appears in ledger.json (a
+    deterministic dedup warning — string membership, not a semantic judgment);
+  * emits a curation WORKLIST the curator then works through by hand.
+
+It does NOT do the SEMANTIC half — triage the domain, classify type/layer/
+mechanism, or judge novelty vs the full canon. Those stay with the curator
+(capability boundary); see design/collection-loop/CURATION-INTAKE.md.
+
+PII boundary: the worklist carries `_provenance.user_email` (D3.3 — visibility
+into who contributes what). The worklist is a LOCAL artifact — never commit it;
+when merging a candidate into the git-tracked ledger.json, keep `learning_id`
+(non-PII dedup key) and DROP `_provenance` (see the procedure doc).
+
+Input:  a learnings-export JSON file (positional arg; '-' or omitted = stdin).
+Output: the worklist JSON to stdout, or to --out FILE.
+"""
+import argparse
+import importlib.util
+import json
+import pathlib
+import sys
+
+REPO = pathlib.Path(__file__).resolve().parent.parent
+LEDGER = REPO / "design" / "session-distill" / "ledger.json"
+FIXTURE = REPO / "design" / "collection-loop" / "fixtures" / "export-sample.json"
+SUPPORTED_SCHEMA_VERSION = 1
+
+
+def die(msg, code=1):
+    print(f"ingest-learnings-export: {msg}", file=sys.stderr)
+    sys.exit(code)
+
+
+def load_checker():
+    """Reuse scripts/check-learning.py as the single validation source."""
+    path = REPO / "scripts" / "check-learning.py"
+    spec = importlib.util.spec_from_file_location("check_learning", path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def load_ledger_learning_ids(path=LEDGER):
+    """learning_ids already present in the ledger (dedup key). Entries sourced
+    from earlier learnings carry a top-level `learning_id`; the historical
+    session-distill entries do not, so they simply contribute nothing here.
+    A missing/unreadable ledger is not fatal — dedup just finds nothing."""
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return set()
+    out = set()
+    for e in data.get("entries", []):
+        lid = e.get("learning_id") if isinstance(e, dict) else None
+        if isinstance(lid, str) and lid:
+            out.add(lid.lower())
+    return out
+
+
+def map_candidate(payload, row):
+    """A validated export row -> a ledger-candidate entry (ledger.json shape).
+    Deterministic fields the record carries are copied; curator-only fields are
+    null for the curator to fill. `_provenance` is worklist-only (strip before
+    the ledger merge)."""
+    cls = payload.get("classification") or {}
+    return {
+        "id": None,                                   # curator assigns (e.g. S4-02)
+        "learning_id": payload.get("learning_id"),    # kept in ledger = dedup key
+        "lesson": payload.get("lesson"),
+        "strength": None,                             # curator: recurrence
+        "verdict": None,                              # curator: novel|partial|principle
+        "criteria": payload.get("criteria", []),
+        "supporting_sessions": payload.get("supporting_sessions", []),
+        "domain": payload.get("domain"),
+        "proposed_domain": payload.get("proposed_domain"),
+        "context": payload.get("context"),            # curator-facing evidence note
+        "classification": {
+            "type": cls.get("type"),
+            "underlying_value": None,
+            "reformulation": None,
+            "meets_promotion_bar": cls.get("meets_bar"),
+            "layer": cls.get("layer"),
+            "mechanism": None,
+            "token_est": None,
+            "consumer_note": None,
+            "split": None,
+            "verification": None,
+            "proposed": False,                        # ledger convention: boolean
+        },
+        "status": "candidate",
+        "_provenance": {
+            "user_email": row.get("user_email"),      # PII — worklist only, strip on merge
+            "received_at": row.get("received_at"),    # server receipt time
+            "created": payload.get("created"),        # user capture time (distinct)
+            "schema_version": payload.get("schema_version"),
+        },
+    }
+
+
+def process_export(export, checker, ledger_ids):
+    """Bucket every export row. Deterministic: input order preserved, no
+    timestamps, so the same input yields byte-identical output."""
+    if not isinstance(export, dict) or not isinstance(export.get("learnings"), list):
+        die("not a learnings-export (expected an object with a `learnings` array)")
+
+    validator = checker.build_validator()
+    domain_values = checker.valid_domain_values()
+
+    entries, rejected, deferred, duplicates, warnings = [], [], [], [], []
+    for i, row in enumerate(export["learnings"]):
+        if not isinstance(row, dict) or not isinstance(row.get("payload"), dict):
+            rejected.append({"index": i, "learning_id": None,
+                             "reasons": ["export row has no payload object"]})
+            continue
+        payload = row["payload"]
+        lid = payload.get("learning_id")
+
+        sv = payload.get("schema_version")
+        if sv != SUPPORTED_SCHEMA_VERSION:
+            deferred.append({"index": i, "learning_id": lid, "schema_version": sv,
+                             "note": "re-export once a v%s-aware intake exists "
+                                     "(row stays available via includeExported)" % sv})
+            continue
+
+        errors = checker.validate_record(payload, validator, domain_values)
+        if errors:
+            rejected.append({"index": i, "learning_id": lid, "reasons": errors})
+            continue
+
+        # server-bug detector: the export's domain column should mirror payload.domain.
+        if row.get("domain") != payload.get("domain"):
+            warnings.append({"index": i, "learning_id": lid,
+                             "detail": "export domain column %r != payload.domain %r"
+                                       % (row.get("domain"), payload.get("domain"))})
+
+        cand = map_candidate(payload, row)
+        if isinstance(lid, str) and lid.lower() in ledger_ids:
+            cand["duplicate_in_ledger"] = True
+            duplicates.append({"index": i, "learning_id": lid})
+        entries.append(cand)
+
+    return {
+        "source": "curation-intake",
+        "generated_from": export.get("source", "learnings-export"),
+        "counts": {"valid": len(entries), "rejected": len(rejected),
+                   "deferred": len(deferred), "duplicates": len(duplicates),
+                   "warnings": len(warnings)},
+        "warnings": warnings,
+        "rejected": rejected,
+        "deferred": deferred,
+        "entries": entries,
+    }
+
+
+def run(export, out_path=None):
+    worklist = process_export(export, load_checker(), load_ledger_learning_ids())
+    text = json.dumps(worklist, ensure_ascii=False, indent=2) + "\n"
+    if out_path and out_path != "-":
+        pathlib.Path(out_path).write_text(text, encoding="utf-8")
+        c = worklist["counts"]
+        print(f"ingest-learnings-export: wrote {out_path} "
+              f"(valid={c['valid']} rejected={c['rejected']} deferred={c['deferred']} "
+              f"duplicates={c['duplicates']})", file=sys.stderr)
+    else:
+        sys.stdout.write(text)
+    return worklist
+
+
+def _self_test():
+    """Verify bucketing against the committed export fixture (the cross-repo
+    contract artifact): valid rows map (cardinality > 0), a bad-domain row is
+    rejected with a domain reason (negative control), a v2 row is deferred not
+    rejected, mapping preserves context + meets_bar rename, and output is
+    deterministic. Exits non-zero on any failure."""
+    export = json.loads(FIXTURE.read_text(encoding="utf-8"))
+    checker = load_checker()
+    w1 = process_export(export, checker, {"0f8c1c2a-4d1e-4abc-9def-000000000001"})
+    w2 = process_export(export, checker, {"0f8c1c2a-4d1e-4abc-9def-000000000001"})
+
+    valid_ids = {e["learning_id"] for e in w1["entries"]}
+    rej_reasons = " ".join(r for row in w1["rejected"] for r in row["reasons"])
+    deferred_svs = {d["schema_version"] for d in w1["deferred"]}
+    full = next((e for e in w1["entries"]
+                 if e["learning_id"] == "0f8c1c2a-4d1e-4abc-9def-000000000002"), None)
+
+    checks = [
+        ("valid rows mapped (cardinality > 0)", w1["counts"]["valid"] >= 3),
+        ("bad-domain row rejected", w1["counts"]["rejected"] >= 1),
+        ("reject reason names the domain (negative control)", "domain" in rej_reasons),
+        ("v2 row deferred, not rejected", deferred_svs == {2}),
+        ("deferred row absent from entries",
+         "0f8c1c2a-4d1e-4abc-9def-00000000000a" not in valid_ids),
+        ("context preserved verbatim", full is not None and full["context"]
+         and "4분짜리" in full["context"]),
+        ("meets_bar -> meets_promotion_bar",
+         full is not None and full["classification"]["meets_promotion_bar"] is True),
+        ("classification.proposed is boolean false",
+         full is not None and full["classification"]["proposed"] is False),
+        ("provenance carries user_email (worklist-only PII)",
+         full is not None and full["_provenance"]["user_email"] == "alice@day1company.co.kr"),
+        ("provenance keeps both created and received_at",
+         full is not None and full["_provenance"]["created"] != full["_provenance"]["received_at"]),
+        ("ledger dedup flags a known learning_id", w1["counts"]["duplicates"] == 1),
+        ("deterministic (same input -> identical output)",
+         json.dumps(w1, ensure_ascii=False) == json.dumps(w2, ensure_ascii=False)),
+    ]
+    failed = [name for name, ok in checks if not ok]
+    if failed:
+        for name in failed:
+            print(f"ingest-learnings-export --self-test: FAIL: {name}", file=sys.stderr)
+        sys.exit(1)
+    print(f"ingest-learnings-export --self-test: OK ({len(checks)} intake checks)")
+
+
+def main():
+    ap = argparse.ArgumentParser(description="Map a learnings export to ledger candidates.")
+    ap.add_argument("export", nargs="?", default="-",
+                    help="learnings-export JSON file ('-' or omitted = stdin)")
+    ap.add_argument("--out", default=None, help="write the worklist here (default: stdout)")
+    ap.add_argument("--self-test", action="store_true",
+                    help="run the intake self-test against the fixture and exit")
+    args = ap.parse_args()
+
+    if args.self_test:
+        _self_test()
+        return
+
+    if args.export == "-":
+        raw = sys.stdin.read()
+    else:
+        try:
+            raw = pathlib.Path(args.export).read_text(encoding="utf-8")
+        except OSError as e:
+            die(f"cannot read export {args.export!r}: {e}")
+    try:
+        export = json.loads(raw)
+    except json.JSONDecodeError as e:
+        die(f"export is not valid JSON: {e}")
+    run(export, args.out)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/install.sh

@@ -23,6 +23,9 @@ set -euo pipefail
 # or env var. Detach stdin so no child (the codex-helm dry-run, pip, git) can
 # block forever on an inherited idle stdin — that is what hangs an install under
 # CI, pipes, and background runs, where stdin stays open but never delivers.
+# `learn` is the one subcommand whose payload IS stdin, so keep the caller's on
+# fd 3 first and hand it back only there; every other path still sees /dev/null.
+exec 3<&0 2>/dev/null || exec 3</dev/null   # tolerate a caller that closed fd 0
 exec </dev/null
 
 # Resolve this script through symlinks before locating the package: npm links the
@@ -562,6 +565,16 @@ PY
   else
     log "note: managed venv/textual unavailable (numbered-prompt fallback applies)"
   fi
+  # A file this installer executes but never ships is invisible from a clone and
+  # fatal on npm, so the payload gate runs wherever it exists (maintainer-side).
+  if [ -x "$REPO/scripts/check-package.sh" ]; then
+    if "$REPO/scripts/check-package.sh" >/dev/null 2>&1; then
+      info "npm payload OK"
+    else
+      log "npm payload incomplete; run scripts/check-package.sh"
+      fail=1
+    fi
+  fi
   # Repo-internal mirror parity is a maintainer gate; only meaningful from a clone.
   if [ -d "$REPO/ko" ] && [ -x "$REPO/scripts/check-parity.sh" ]; then
     if "$REPO/scripts/check-parity.sh" >/dev/null 2>&1; then info "repo mirror parity OK"; else log "repo mirror parity FAILED"; fail=1; fi
@@ -688,6 +701,9 @@ agent-bios — deploy the Claude/Codex instruction SSOT into $HOME (by copy).
   agent-bios install     deploy into this environment (backs up + verifies)
   agent-bios onboard     interactive domain selection + packaged install + activation canary
   agent-bios verify      check the deployed state matches the source
+  agent-bios learn       submit a session learning (reads the JSON record on
+                         stdin; this is what the learn! flow calls, and it
+                         works from any directory, unlike a repo-relative path)
   agent-bios status      show what is installed and where
   agent-bios update      git pull + reinstall (clone), or print the npm update line
   agent-bios uninstall   remove deployed files and the zsh hook
@@ -713,6 +729,18 @@ EOF
 # ---- dispatch ------------------------------------------------------------
 CMD="${1:-help}"
 if [ $# -gt 0 ]; then shift; fi
+
+# `learn` forwards its arguments and stdin straight to the collector, so it must
+# bypass the flag parser below (which rejects anything it does not know). This
+# subcommand is the only PATH-reachable entry to capture: the corpus guide used
+# to invoke scripts/collect-learning.py relative to the cwd, which works from a
+# clone and silently fails for every other install.
+if [ "$CMD" = "learn" ]; then
+  collector="$REPO/scripts/collect-learning.py"
+  [ -f "$collector" ] || { log "learn: collector missing at $collector"; exit 1; }
+  exec python3 "$collector" "$@" <&3
+fi
+
 WITH=""
 DOMAINS_ARG=""
 DOMAINS_SET=0

package/scripts/session-cost.py

@@ -2,7 +2,8 @@
 """Aggregate token usage & cost for a Claude Code session (main + subagents).
 
 Usage: session-cost.py <session>.jsonl [...]
-Reads the session transcript and, if present, <session-dir>/subagents/agent-*.jsonl.
+Reads the session transcript, splitting main-loop from subagent (sidechain)
+usage, and also picks up <session-dir>/subagents/agent-*.jsonl when present.
 Prints per-source, per-model token sums, modeled cost, and wall-clock span.
 """
 import json, sys, glob, os
@@ -28,9 +29,17 @@ def price_for(model):
     return None
 
 def scan(path):
-    """-> {model: {in,out,cr,cw5,cw1,turns}}, (t_min, t_max)"""
-    agg, tmin, tmax, seen = {}, None, None, set()
-    for line in open(path):
+    """-> {(scope, model): {in,out,cr,cw5,cw1,turns}}, (t_min, t_max), {scope: agent_ids}
+
+    A single API response is written to the transcript several times as it
+    streams, each line carrying output_tokens *so far* (e.g. 2, 2, 2, 540).
+    Keep the record with the LARGEST output_tokens per message id: keeping the
+    first one instead under-reports subagent output by ~95%, because sidechain
+    messages get snapshotted far more often than main-loop ones do.
+    """
+    best, tmin, tmax = {}, None, None
+    agents = {"main": set(), "sub": set()}
+    for line in open(path, errors="replace"):
         try:
             d = json.loads(line)
         except json.JSONDecodeError:
@@ -42,11 +51,17 @@ def scan(path):
         u, model = m.get("usage"), m.get("model")
         if not u or not model or model == "<synthetic>":
             continue
-        rid = m.get("id") or d.get("requestId")
-        if rid in seen:
-            continue  # one usage record per API request
-        seen.add(rid)
-        a = agg.setdefault(model, dict(inp=0, out=0, cr=0, cw5=0, cw1=0, turns=0))
+        scope = "sub" if d.get("isSidechain") else "main"
+        if d.get("agentId"):
+            agents[scope].add(d["agentId"])
+        key = (scope, m.get("id") or d.get("requestId"))
+        prev = best.get(key)
+        if prev is None or u.get("output_tokens", 0) > prev[1].get("output_tokens", 0):
+            best[key] = (model, u)
+
+    agg = {}
+    for (scope, _), (model, u) in best.items():
+        a = agg.setdefault((scope, model), dict(inp=0, out=0, cr=0, cw5=0, cw1=0, turns=0))
         a["inp"] += u.get("input_tokens", 0)
         a["out"] += u.get("output_tokens", 0)
         a["cr"]  += u.get("cache_read_input_tokens", 0)
@@ -57,7 +72,7 @@ def scan(path):
         else:
             a["cw5"] += u.get("cache_creation_input_tokens", 0)
         a["turns"] += 1
-    return agg, (tmin, tmax)
+    return agg, (tmin, tmax), agents
 
 def cost(model, a):
     p = price_for(model)
@@ -71,19 +86,27 @@ def fmt(n):
 
 def report(session_path):
     base = session_path[:-6]  # strip .jsonl
-    sources = [("main", session_path)]
+    sources = [(None, session_path)]
     sources += [(os.path.basename(f)[:-6], f)
                 for f in sorted(glob.glob(os.path.join(base, "subagents", "*.jsonl")))]
     print(f"\n=== {os.path.basename(session_path)} ===")
     grand, unpriced = 0.0, []
-    hdr = f"{'source':<38}{'model':<22}{'turns':>6}{'input':>9}{'output':>9}{'cache_rd':>10}{'cache_wr':>10}{'cost$':>9}"
+    hdr = (f"{'source':<38}{'model':<22}{'turns':>6}{'input':>9}{'output':>9}"
+           f"{'cache_rd':>10}{'cache_wr':>10}{'cost$':>9}")
     print(hdr); print("-" * len(hdr))
     span_min = span_max = None
-    for name, path in sources:
-        agg, (tmin, tmax) = scan(path)
+    for label, path in sources:
+        agg, (tmin, tmax), agents = scan(path)
         if tmin:
             span_min = min(span_min or tmin, tmin); span_max = max(span_max or tmax, tmax)
-        for model, a in agg.items():
+        for (scope, model), a in sorted(agg.items()):
+            if label is not None:
+                name = label
+            elif scope == "sub":
+                n = len(agents["sub"])
+                name = f"subagents (n={n})" if n else "subagents"
+            else:
+                name = "main"
             c = cost(model, a)
             cs = f"{c:9.2f}" if c is not None else "        ?"
             if c is None: