@cohortapp/agent-sdk 2.3.0

package/scripts/pre_draft_lookup.py

@@ -0,0 +1,258 @@
+#!/usr/bin/env python3
+"""Pre-draft context lookup wrapper — Memory Enhancement Phase 7.
+
+Thin wrapper around pre-draft-context.py that:
+  1. Calls retrieve_context() for a recipient
+  2. Logs the result to logs/audit/{date}-pre-draft-lookups.jsonl
+  3. Returns the context dict (or None) without blocking
+
+Designed for import into send scripts. Fail-open: if anything goes wrong,
+logs the error and returns None — never blocks a send.
+
+Usage (Python import):
+    from pre_draft_lookup import pre_draft_lookup
+    context = pre_draft_lookup("<recipient name>", message_type="slack")
+
+Usage (CLI — for shell scripts):
+    python3 scripts/pre_draft_lookup.py --recipient "<recipient name>" --type slack --channel C099ABC
+
+Created: 2026-04-04 — Memory Enhancement Phase 7
+"""
+import json
+import os
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+REPO_ROOT = SCRIPT_DIR.parent
+AUDIT_LOG_DIR = REPO_ROOT / "logs" / "audit"
+
+# Import pre-draft-context module (same directory)
+_pdc_module = None
+try:
+    # pre-draft-context.py uses a hyphen in the filename, so we use the
+    # importlib approach or just add the scripts dir to sys.path and
+    # import the module that was saved as pre_draft_context.py equivalent.
+    # Actually, the file is scripts/pre-draft-context.py — we need importlib.
+    import importlib.util
+    pdc_path = SCRIPT_DIR / "pre-draft-context.py"
+    if pdc_path.exists():
+        spec = importlib.util.spec_from_file_location("pre_draft_context", str(pdc_path))
+        _pdc_module = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(_pdc_module)
+except Exception:
+    pass
+
+# Import disclosure boundaries module (same directory)
+_db_module = None
+try:
+    import importlib.util as _db_ilu
+    _db_path = SCRIPT_DIR / "disclosure_boundaries.py"
+    if _db_path.exists():
+        _db_spec = _db_ilu.spec_from_file_location("disclosure_boundaries", str(_db_path))
+        _db_mod = _db_ilu.module_from_spec(_db_spec)
+        _db_spec.loader.exec_module(_db_mod)
+        generate_disclosure_boundaries = _db_mod.generate_disclosure_boundaries
+        _db_module = True
+except Exception:
+    pass
+
+
+def _log_lookup(record):
+    """Append a lookup record to the daily audit log (JSONL). Best-effort."""
+    try:
+        AUDIT_LOG_DIR.mkdir(parents=True, exist_ok=True)
+        date_str = datetime.now(timezone.utc).strftime("%Y-%m-%d")
+        log_path = AUDIT_LOG_DIR / f"{date_str}-pre-draft-lookups.jsonl"
+        with open(log_path, "a", encoding="utf-8") as f:
+            f.write(json.dumps(record, default=str, ensure_ascii=False) + "\n")
+    except Exception:
+        pass  # Never fail on logging
+
+
+def pre_draft_lookup(recipient, message_type="email", channel=None, topic=None):
+    """Look up recipient context before sending a message.
+
+    Args:
+        recipient: Name, email, or Slack channel ID of the recipient.
+        message_type: "email" or "slack".
+        channel: Optional channel/thread identifier for logging.
+        topic: Optional topic to filter context.
+
+    Returns:
+        dict with context, or None if lookup fails or recipient not found.
+        Never raises — always fail-open.
+    """
+    t0 = time.time()
+    timestamp = datetime.now(timezone.utc).isoformat()
+
+    log_record = {
+        "timestamp": timestamp,
+        "recipient": recipient,
+        "message_type": message_type,
+        "channel": channel,
+        "topic": topic,
+        "status": "error",
+        "entity_found": False,
+        "facts_count": 0,
+        "critical_facts": [],
+        "lookup_ms": 0,
+    }
+
+    if _pdc_module is None:
+        log_record["status"] = "module_unavailable"
+        log_record["error"] = "pre-draft-context.py could not be imported"
+        log_record["lookup_ms"] = round((time.time() - t0) * 1000, 1)
+        _log_lookup(log_record)
+        return None
+
+    try:
+        context = _pdc_module.retrieve_context(recipient, topic)
+        elapsed_ms = round((time.time() - t0) * 1000, 1)
+        log_record["lookup_ms"] = elapsed_ms
+
+        if context is None:
+            log_record["status"] = "not_found"
+            _log_lookup(log_record)
+            return None
+
+        # Context found — extract key details for audit log
+        log_record["status"] = "found"
+        log_record["entity_found"] = True
+
+        r = context.get("recipient", {})
+        log_record["entity_name"] = r.get("name", "")
+        log_record["entity_id"] = r.get("entity_id", "")
+        log_record["relationship_type"] = context.get("relationship", {}).get("type", "")
+        log_record["is_internal"] = context.get("relationship", {}).get("is_internal", False)
+
+        # Count facts
+        facts_count = 0
+        standing = context.get("communication", {}).get("standing_instructions", [])
+        if isinstance(standing, list):
+            facts_count += len(standing)
+        facts_count += len(context.get("active_queue_items", []))
+        facts_count += len(context.get("related_entities", []))
+        facts_count += len(context.get("recent_interactions", []))
+        log_record["facts_count"] = facts_count
+
+        # Extract critical facts — things that could cause errors if ignored
+        critical_facts = []
+        # Check notes for negation patterns (e.g., "NOT a co-founder")
+        notes = r.get("notes", "") or ""
+        if notes:
+            # Flag notes containing "NOT", "never", "do not"
+            for pattern in ["NOT ", "never ", "do not ", "don't ", "is not "]:
+                if pattern.lower() in notes.lower():
+                    critical_facts.append(f"ENTITY NOTE: {notes}")
+                    break
+
+        # Check standing instructions for critical items
+        if isinstance(standing, list):
+            for instr in standing:
+                instr_str = str(instr).lower()
+                if any(w in instr_str for w in ["never", "not ", "don't", "do not", "avoid", "critical"]):
+                    critical_facts.append(f"STANDING INSTRUCTION: {instr}")
+
+        # Check relationship type warnings
+        rel_type = context.get("relationship", {}).get("type", "")
+        company_rels = context.get("relationship", {}).get("company_relationships", [])
+        for ar in company_rels:
+            ar_notes = ar.get("notes", "") or ""
+            if ar_notes and any(w in ar_notes.lower() for w in ["not ", "never", "conditional", "pending"]):
+                critical_facts.append(f"RELATIONSHIP NOTE: {ar_notes}")
+
+        log_record["critical_facts"] = critical_facts
+        if critical_facts:
+            log_record["has_critical_facts"] = True
+
+        # ── Disclosure Boundaries (Information Barrier Layer 1) ──
+        disclosure_boundaries = None
+        if _db_module:
+            try:
+                entity_name = r.get("name", "") or recipient
+                slug = entity_name.lower().replace(" ", "-")
+                disclosure_boundaries = generate_disclosure_boundaries(slug)
+                if disclosure_boundaries:
+                    context["disclosure_boundaries"] = disclosure_boundaries
+                    log_record["disclosure_boundaries_generated"] = True
+                    log_record["active_conflicts_count"] = len(
+                        disclosure_boundaries.get("active_conflicts", [])
+                    )
+                    log_record["excluded_domains_count"] = len(
+                        disclosure_boundaries.get("excluded_domains_active", [])
+                    )
+                    log_record["recent_sensitive_count"] = len(
+                        disclosure_boundaries.get("recent_sensitive_context", [])
+                    )
+            except Exception:
+                log_record["disclosure_boundaries_generated"] = False
+
+        _log_lookup(log_record)
+        return context
+
+    except Exception as e:
+        log_record["status"] = "error"
+        log_record["error"] = str(e)
+        log_record["lookup_ms"] = round((time.time() - t0) * 1000, 1)
+        _log_lookup(log_record)
+        return None
+
+
+def format_context_brief(context):
+    """Format context as a brief string summary. Delegates to pre-draft-context module."""
+    if _pdc_module is None:
+        return ""
+    try:
+        return _pdc_module.format_brief(context)
+    except Exception:
+        return ""
+
+
+# ─────────────────────────────────────────────
+# CLI entry point (for shell script integration)
+# ─────────────────────────────────────────────
+def main():
+    import argparse
+    parser = argparse.ArgumentParser(
+        description="Pre-draft context lookup wrapper — logs results to audit trail."
+    )
+    parser.add_argument("--recipient", required=True, help="Recipient name or email")
+    parser.add_argument("--type", dest="message_type", default="email",
+                        choices=["email", "slack"], help="Message type")
+    parser.add_argument("--channel", default=None, help="Channel/thread ID for logging")
+    parser.add_argument("--topic", default=None, help="Optional topic filter")
+    args = parser.parse_args()
+
+    context = pre_draft_lookup(
+        args.recipient,
+        message_type=args.message_type,
+        channel=args.channel,
+        topic=args.topic,
+    )
+
+    if context is None:
+        print("PRE_DRAFT_LOOKUP: No context found for recipient", file=sys.stderr)
+        sys.exit(0)  # Exit 0 — not finding context is not an error
+
+    brief = format_context_brief(context)
+    if brief:
+        print(f"PRE_DRAFT_CONTEXT:\n{brief}", file=sys.stderr)
+
+    # Output JSON to stdout for potential downstream consumption
+    print(json.dumps({
+        "status": "found",
+        "entity_name": context.get("recipient", {}).get("name", ""),
+        "entity_id": context.get("recipient", {}).get("entity_id", ""),
+        "relationship_type": context.get("relationship", {}).get("type", ""),
+        "facts_count": len(context.get("active_queue_items", [])) +
+                       len(context.get("related_entities", [])) +
+                       len(context.get("recent_interactions", [])),
+    }, default=str))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/rag/build-index.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * build-index.mjs — Run the RAG indexer against the current agent repo.
+ *
+ * Usage:
+ *   node scripts/rag/build-index.mjs                 # incremental
+ *   node scripts/rag/build-index.mjs --force         # rebuild every file
+ *   node scripts/rag/build-index.mjs --stats         # print stats only
+ *
+ * Designed to run from `maestro init rag-foundation --apply`, from
+ * `maestro upgrade` post-hook, and as a periodic refresh job (e.g.
+ * every N hours via launchd) so the index stays fresh against new
+ * memory / decisions / briefs.
+ */
+
+import { buildIndex } from "../../lib/rag/indexer.mjs";
+import { stats as ragStats } from "../../lib/rag/search.mjs";
+
+const args = new Set(process.argv.slice(2));
+const force = args.has("--force");
+const statsOnly = args.has("--stats");
+const quiet = args.has("--quiet");
+
+const ok = (m) => !quiet && process.stdout.write(`[rag-index]  ✓ ${m}\n`);
+const info = (m) => !quiet && process.stdout.write(`[rag-index]  · ${m}\n`);
+
+const AGENT_ROOT = process.env.AGENT_ROOT || process.env.AGENT_DIR || process.cwd();
+info(`agent root: ${AGENT_ROOT}`);
+
+if (statsOnly) {
+  const s = await ragStats({ agentRoot: AGENT_ROOT });
+  process.stdout.write(JSON.stringify(s, null, 2) + "\n");
+  process.exit(0);
+}
+
+const result = await buildIndex({
+  agentRoot: AGENT_ROOT,
+  force,
+  log: (level, message) => !quiet && process.stdout.write(`[rag-index] ${level}: ${message}\n`),
+});
+ok(`indexed: +${result.added} new, ~${result.updated} updated, -${result.deleted} purged, =${result.unchanged} unchanged`);
+ok(`${result.chunks} new/updated chunks written`);
+ok(`took ${(result.took_ms / 1000).toFixed(1)}s`);
+
+const s = await ragStats({ agentRoot: AGENT_ROOT });
+ok(`total: ${s.files} files / ${s.chunks} chunks / ${(s.db_size_bytes / 1024).toFixed(0)} KB`);
+info(`by kind: ${JSON.stringify(s.by_kind)}`);

package/scripts/rag/ingest.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+/**
+ * scripts/rag/ingest.mjs — Inventory step for the cross-repo RAG.
+ *
+ * Walks every repo flagged `index: true` in config/repo-registry.yaml,
+ * counts files / lines per language, and writes a summary to
+ * state/rag/inventory.json. The MVP search surface (scripts/rag/search.mjs)
+ * is grep-based so it doesn't need an actual embedding index yet, but the
+ * inventory lets `maestro doctor` confirm the configured repos are
+ * accessible and roughly the size the agent expects.
+ *
+ * Future: replace with embedding pipeline + sqlite-fts5 or vector store.
+ */
+
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync, readdirSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+
+const ok = (m) => process.stdout.write(`[rag-ingest]  ✓ ${m}\n`);
+const warn = (m) => process.stdout.write(`[rag-ingest]  ⚠ ${m}\n`);
+
+const registryPath = join(AGENT_DIR, "config/repo-registry.yaml");
+if (!existsSync(registryPath)) {
+  warn("config/repo-registry.yaml not found — run `maestro init rag-foundation --apply` first.");
+  process.exit(0);
+}
+
+const body = readFileSync(registryPath, "utf-8");
+const repos = [];
+let cur = null;
+for (const raw of body.split("\n")) {
+  const line = raw.replace(/#.*$/, "").trimEnd();
+  if (line.match(/^\s*-\s+name:\s*(.+)$/)) {
+    if (cur) repos.push(cur);
+    cur = { name: line.replace(/^\s*-\s+name:\s*/, "").replace(/['"]/g, "").trim() };
+  } else if (cur && line.match(/^\s+path:\s*(.+)$/)) {
+    cur.path = line.replace(/^\s+path:\s*/, "").replace(/['"]/g, "").trim().replace(/^~/, process.env.HOME || "~");
+  } else if (cur && line.match(/^\s+index:\s*(true|false)/)) {
+    cur.index = /true/.test(line);
+  }
+}
+if (cur) repos.push(cur);
+
+mkdirSync(join(AGENT_DIR, "state/rag"), { recursive: true });
+
+const EXT_BUCKETS = {
+  ts: [".ts", ".tsx"],
+  js: [".js", ".mjs", ".cjs"],
+  py: [".py"],
+  go: [".go"],
+  rs: [".rs"],
+  java: [".java"],
+  yaml: [".yaml", ".yml"],
+  json: [".json"],
+  md: [".md", ".mdx"],
+  sh: [".sh", ".bash"],
+};
+const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", "target", ".next", "__pycache__", ".venv", "venv"]);
+
+function bucketFor(filename) {
+  for (const [bucket, exts] of Object.entries(EXT_BUCKETS)) {
+    for (const ext of exts) if (filename.endsWith(ext)) return bucket;
+  }
+  return null;
+}
+
+function walk(root) {
+  const counts = { files: 0, by_lang: {} };
+  function visit(dir) {
+    let entries;
+    try { entries = readdirSync(dir); } catch { return; }
+    for (const name of entries) {
+      if (SKIP_DIRS.has(name)) continue;
+      const full = join(dir, name);
+      let st;
+      try { st = statSync(full); } catch { continue; }
+      if (st.isDirectory()) visit(full);
+      else if (st.isFile()) {
+        const b = bucketFor(name);
+        if (!b) continue;
+        counts.files += 1;
+        counts.by_lang[b] = (counts.by_lang[b] || 0) + 1;
+      }
+    }
+  }
+  visit(root);
+  return counts;
+}
+
+const inventory = {
+  generated_at: new Date().toISOString(),
+  repos: [],
+};
+
+for (const repo of repos) {
+  if (!repo.path || repo.index === false) continue;
+  if (!existsSync(repo.path)) {
+    inventory.repos.push({ name: repo.name, path: repo.path, status: "missing" });
+    warn(`${repo.name}: path missing (${repo.path})`);
+    continue;
+  }
+  const counts = walk(repo.path);
+  inventory.repos.push({ name: repo.name, path: repo.path, status: "indexed", ...counts });
+  ok(`${repo.name}: ${counts.files} indexable files`);
+}
+
+writeFileSync(join(AGENT_DIR, "state/rag/inventory.json"), JSON.stringify(inventory, null, 2) + "\n");
+ok(`wrote state/rag/inventory.json (${inventory.repos.length} repo(s))`);

package/scripts/rag/search.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+/**
+ * scripts/rag/search.mjs — Cross-repo code search for the operating agent.
+ *
+ * Reads config/repo-registry.yaml, runs ripgrep across every repo flagged
+ * `index: true`, and returns a JSON list of matches. This is the MVP RAG
+ * surface — no embeddings yet, just fast literal/regex search across the
+ * agent's authorised codebase set. Embeddings + chunk-level retrieval
+ * land in a future feature-init step.
+ *
+ * Usage:
+ *   node scripts/rag/search.mjs <query> [--regex] [--limit=N] [--lang=ts,py,...]
+ *
+ * Output: JSON object with { query, repos_searched, matches: [...] }.
+ * Designed to be called as a tool from a Claude session.
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENT_DIR = process.env.AGENT_ROOT || process.env.AGENT_DIR || resolve(__dirname, "..", "..");
+
+function fail(msg) { process.stderr.write(`[rag-search] ${msg}\n`); process.exit(1); }
+
+const args = process.argv.slice(2);
+let query = null;
+let useRegex = false;
+let limit = 50;
+let langs = null;
+for (const a of args) {
+  if (a === "--regex") useRegex = true;
+  else if (a.startsWith("--limit=")) limit = parseInt(a.slice(8), 10) || 50;
+  else if (a.startsWith("--lang=")) langs = a.slice(7).split(",").map((s) => s.trim()).filter(Boolean);
+  else if (!a.startsWith("--")) { query = query ? `${query} ${a}` : a; }
+}
+if (!query) fail("usage: search.mjs <query> [--regex] [--limit=N] [--lang=ts,py,...]");
+
+// Parse YAML registry (just the lines we need — no YAML lib).
+const registryPath = join(AGENT_DIR, "config/repo-registry.yaml");
+if (!existsSync(registryPath)) fail(`config/repo-registry.yaml not found — run \`maestro init rag-foundation --apply\``);
+
+const body = readFileSync(registryPath, "utf-8");
+const repos = [];
+let cur = null;
+for (const raw of body.split("\n")) {
+  const line = raw.replace(/#.*$/, "").trimEnd();
+  if (line.match(/^\s*-\s+name:\s*(.+)$/)) {
+    if (cur) repos.push(cur);
+    cur = { name: line.replace(/^\s*-\s+name:\s*/, "").replace(/['"]/g, "").trim() };
+  } else if (cur && line.match(/^\s+path:\s*(.+)$/)) {
+    cur.path = line.replace(/^\s+path:\s*/, "").replace(/['"]/g, "").trim().replace(/^~/, process.env.HOME || "~");
+  } else if (cur && line.match(/^\s+index:\s*(true|false)/)) {
+    cur.index = /true/.test(line);
+  }
+}
+if (cur) repos.push(cur);
+
+const indexed = repos.filter((r) => r.path && (r.index !== false));
+if (indexed.length === 0) fail("no repos marked index: true in repo-registry.yaml");
+
+// Use ripgrep if available; fall back to grep -r.
+const rg = spawnSync("which", ["rg"], { encoding: "utf-8" });
+const hasRg = rg.status === 0;
+const matches = [];
+let scanned = 0;
+
+for (const repo of indexed) {
+  if (!existsSync(repo.path)) continue;
+  scanned += 1;
+  const rgArgs = [
+    "--json",
+    "--max-count", String(Math.min(limit, 50)),
+    "--max-columns", "240",
+    "--no-heading",
+  ];
+  if (!useRegex) rgArgs.push("--fixed-strings");
+  if (langs) for (const l of langs) rgArgs.push("-t", l);
+  rgArgs.push(query, repo.path);
+
+  if (!hasRg) {
+    // Fallback to grep.
+    const r = spawnSync("grep", ["-rn", useRegex ? "-E" : "-F", "--", query, repo.path], {
+      encoding: "utf-8",
+      maxBuffer: 16 * 1024 * 1024,
+    });
+    for (const line of (r.stdout || "").split("\n")) {
+      if (!line) continue;
+      const m = line.match(/^([^:]+):(\d+):(.*)$/);
+      if (!m) continue;
+      matches.push({ repo: repo.name, path: m[1], line: parseInt(m[2], 10), excerpt: m[3].slice(0, 240) });
+      if (matches.length >= limit) break;
+    }
+  } else {
+    const r = spawnSync("rg", rgArgs, { encoding: "utf-8", maxBuffer: 16 * 1024 * 1024 });
+    for (const line of (r.stdout || "").split("\n")) {
+      if (!line) continue;
+      let entry;
+      try { entry = JSON.parse(line); } catch { continue; }
+      if (entry.type !== "match" || !entry.data) continue;
+      const path = entry.data.path?.text || "";
+      const lineNum = entry.data.line_number || 0;
+      const text = entry.data.lines?.text || "";
+      matches.push({ repo: repo.name, path, line: lineNum, excerpt: text.slice(0, 240) });
+      if (matches.length >= limit) break;
+    }
+  }
+  if (matches.length >= limit) break;
+}
+
+process.stdout.write(JSON.stringify({
+  query,
+  use_regex: useRegex,
+  repos_searched: scanned,
+  match_count: matches.length,
+  matches,
+}, null, 2) + "\n");