@cohortapp/agent-sdk 2.3.0

package/docs/architecture/archetype-agent-factory.md

@@ -0,0 +1,110 @@
+# The Archetype Agent Factory
+
+> How Maestro turns a chosen archetype into a complete, ready-to-operate
+> autonomous agent — McKinsey/Goldman-grade, generated from data, busy from
+> minute one. Persona-agnostic: every example below is illustrative.
+
+## 1. The model: Function × Altitude
+
+An agent's operating model is composed from **two orthogonal axes**, not one:
+
+- **Function** — *what the agent owns*: control towers, KPI categories,
+  stakeholders, backlog streams, tool/skill/workflow packs, and the MCP servers
+  the role needs. Six functions: `executive-operator`, `technical-leader`,
+  `commercial-leader`, `compliance-officer`, `product-leader`, `operations-leader`.
+- **Altitude** — *how the agent operates*: autonomy bands, decision-rights
+  authority, escalation thresholds, KPI altitude, backlog granularity, delegation
+  breadth, and communication formality. Five altitudes: `founder`, `c-suite`,
+  `svp`, `vp`, `senior-manager`.
+
+Seniority roles decompose into cells: a **CTO** = `technical-leader × c-suite`; a
+**VP of Engineering** = `technical-leader × vp`; a **Head of Operations** =
+`operations-leader × svp`; a **Startup Founder** = `executive-operator × founder`.
+The same function at two altitudes shares skills and towers but has radically
+different decision rights and autonomy — which a single-axis model cannot express.
+
+## 2. The data spine
+
+The operating model is **data, not prose** — versioned, validatable, diffable:
+
+```
+archetypes/
+├── base.yaml                  shared defaults (voice modes, principles, universal reds)
+├── functions/<function>.yaml  towers, KPIs, stakeholders, backlog streams, packs
+├── altitudes/<altitude>.yaml  autonomy bands, decision-rights, escalation, granularity
+├── capabilities/<function>.yaml   the role's sub-agent org (teams of roles), skills,
+│                                  workflows, MCP servers
+└── archetype.schema.json      the resolved-profile contract
+```
+
+Resolved by small, tested, dependency-light modules:
+
+| Module | Resolves |
+| --- | --- |
+| `lib/archetype.mjs` | `base ⊕ function ⊕ altitude` → validated operating profile |
+| `lib/capability.mjs` | standard defaults + altitude-scaled role roster + skills/workflows/MCP |
+| `lib/cadences.mjs` | standard ⊕ function recurring workflows ⊕ altitude cadences |
+| `lib/autonomy.mjs` | the action-classification policy (human bands + enforced per-action map) |
+| `lib/comms.mjs` | tone/register/voice-modes/channel-strategy/templates |
+| `lib/charter.mjs`, `lib/backlog.mjs` | the operating charter + the WBS backlog |
+| `lib/render.mjs` | `{{agent.*}}` token substitution (framework prompts stay generic) |
+
+## 3. The generation pipeline (init Phase 2.5)
+
+A chosen `{ function, altitude }` + a hybrid **context pack** (a short interview for
+what only the principal knows + autonomous research) drives the generators:
+
+```
+config/agent.json {function, altitude}
+        │  resolveArchetype  →  operating profile
+        ▼
+ init-archetype  →  validate + normalise
+ generate-charter   →  config/operating-charter.md   (towers, RACI/decision-rights,
+                                                       autonomy, KPI tree, stakeholders, 30/60/90)
+ generate-backlog   →  state/backlog/wbs.yaml + seeded state/queues/* + config/priorities.yaml
+ generate-capability→  agents/*/agent.md (40–60 role + 13 standard), plugins/agent-skills/,
+                       workflows/*, config/{agent-roster,event-routing,mcp-servers}.yaml
+ generate-cadences  →  config/cadences.yaml + launchd plists (archetype-specific schedule)
+ generate-autonomy  →  policies/action-classification.yaml (archetype-derived + gate-enforced)
+ generate-comms     →  policies/communication-profile.yaml (tone/register/channels)
+```
+
+Skeletons are deterministic from the data spine; the wizard LLM-enriches the
+company-specific content from the context pack. Every artifact is reviewed before
+it goes live, and a **doctor acceptance gate** refuses to call init "done" until
+the agent can actually work (charter present & placeholder-free, priorities
+populated, backlog seeded, capability surface generated).
+
+## 4. What a freshly-initialised agent gets
+
+Worked example — a fresh **VP, Regulatory & Licensing** (`compliance-officer × vp`):
+
+- a 150-line **operating charter** (purpose, 8 control towers, a VP-calibrated
+  decision-rights matrix, Green/Amber/Red autonomy, escalation, KPI tree,
+  stakeholder map, first-90-days);
+- a **seeded backlog** — streams → 30/60/90 phases → epics → tasks, with the
+  first-30-day tasks materialised as `open` queue items the backlog-executor
+  works on the first tick;
+- a **capability surface** — ~45 sub-agents (13 standard infrastructure + ~32
+  role-tailored, altitude-scaled), 8 skills, 7 workflows, 6 MCP servers, and an
+  event→capability routing table;
+- **archetype-specific cadences** (a compliance rhythm, not an engineering one);
+- an **enforced autonomy policy** calibrated to the altitude (a VP escalates
+  binding external commitments; a founder owns them);
+- a **communication profile** (register, formality, channel strategy, voice modes).
+
+A C-suite altitude scales the same function up to ~65 sub-agents and broader
+autonomy; a senior-manager scales it down to a hands-on core. The agent gets
+straight to work — on role-true, company-specific work — the moment the daemon starts.
+
+## 5. Why it's enterprise-grade
+
+- **Reproducible & auditable** — two same-archetype agents get byte-identical
+  skeletons; the operating model is data a risk committee can read and diff.
+- **Versioned** — the archetype library is registered in `framework-features.json`;
+  `upgrade` re-renders charters/backlogs/cadences when it revs.
+- **Enforced, not decorative** — autonomy bands compile to the per-action map the
+  comms/voice gate reads; CI guards keep confidential data and residual identity
+  out of the published framework.
+- **Persona-agnostic** — framework prompts carry `{{agent.*}}` tokens rendered at
+  load time; only generated per-agent artifacts carry a name.

package/docs/architecture/collective-memory-and-org-mesh.md

@@ -0,0 +1,115 @@
+# Collective Memory & Org Mesh
+
+> Cross-session global memory, concurrent-session presence, and inter-agent org
+> coordination for Maestro. Status: implemented (file-backed, cohort-ready).
+
+## Why
+
+A senior operator — human or AI — arriving at work needs, within seconds:
+
+1. **"What do I already know / what happened while I was away?"** → collective memory
+2. **"Who else is working right now, and on what?"** → presence
+3. **"Who's who in the org, what do they own, what are they heads-down on, and how
+   do I reach them or hand work off?"** → org mesh
+
+…and every AI action must stay **observable by the responsible humans**.
+
+Maestro already had the raw materials (per-agent FTS5 RAG, atomic session locks,
+a channel bus, and charter/backlog/archetype data) but no layer that made any of
+it *collective* across sessions or *legible* across agents. This feature adds that
+layer. **Anti-bloat is the spine**: nothing here is allowed to balloon a session's
+context — capture is distilled and async, recall is hard token-budgeted.
+
+## Three pillars
+
+### Pillar 1 — Collective memory (`lib/collective/`)
+
+Every Claude Code session **on the machine** (not just daemon sessions — also the
+operator's ad-hoc `claude` runs in any repo) contributes to, and recalls from, the
+agent's long-term memory.
+
+- **Capture (write).** A global `Stop`/`PreCompact` hook distills the finished
+  session (cheap model, async, time-boxed, **fail-open**) into small structured
+  **memory cards** — `decision | fact | artifact | openloop | entity` — and appends
+  them to `memory/collective/cards/<date>.jsonl`. **Never raw transcripts.** Trivial
+  sessions (no tool use / too short) are skipped. Honors a repo **denylist** and the
+  information-barrier policy.
+- **Store.** `memory/collective/` is registered as a source for the *existing*
+  `lib/rag` FTS5 (+ optional embedding) index — reused, not rebuilt.
+- **Recall (read).** A global `SessionStart` hook injects a **hard token-budgeted
+  digest** (`digestBudgetTokens`, default 1500): a one-line presence summary + the
+  top cards ranked by **relevance × recency-decay × salience**, MMR-deduped, plus a
+  pointer to `rag_search` / `collective recall` for more. The budget is the
+  anti-bloat control.
+- **Cross-repo reach.** `~/.claude/maestro-agent.json` (written at `global-setup`)
+  names the agent repo so sessions in *any* directory find the store; absent → the
+  hooks no-op silently (safe on non-agent machines).
+
+### Pillar 2 — Presence (`lib/collective/presence.mjs`)
+
+A file-backed session registry under `state/collective/presence/<sessionId>.json`,
+using the same atomic-`wx` + fail-open idiom as `session-lock.mjs`. Each session
+`register()`s on start, `heartbeat()`s on PostToolUse, and `deregister()`s on stop;
+stale entries (no beat past `staleSec`) are reaped on read. Surfaced as the one-line
+summary in the SessionStart digest ("2 other sessions active — daemon: inbox triage
+(4m); ~/openclaw: interactive (just now)"), and via `scripts/collective/who.mjs`.
+
+### Pillar 3 — Org mesh (`lib/org/`)
+
+- **Registry SoT.** `buildSelfEntry()` assembles this agent's directory entry from
+  data that already exists: identity (`config/agent.json`) + archetype
+  (function×altitude) + charter towers/decision-rights/autonomy + live backlog focus
+  (`state/queues`) + presence + comms coordinates. Published **file-backed**
+  (`state/org/self.json` + a merged `state/org/directory.json`) — works today, zero
+  infra — with a **cohort API client behind a flag** (`org.cohort.enabled`) that
+  publishes status + fetches the directory from `api.cohortapp.com/{org}/agents`,
+  aligned to the contract wundr's orchestrator-daemon already speaks. The human org
+  chart is a **pluggable directory source** (`file` | `google` | `slack`) wired when
+  credentials exist.
+- **A2A handoff.** `sendHandoff()` emits a structured ` ```maestro-handoff ` JSON
+  envelope over the **existing Slack/email channel bus** to the target agent's
+  coordinates; the receiving daemon's classifier recognizes the envelope and enqueues
+  a provenance-tagged task. Because handoffs ride Slack/email, **humans see every
+  one** — observability by construction. Each is mirrored to `state/org/handoffs.jsonl`
+  and (optionally) a human channel.
+- **Observability.** An `org-pulse` cadence posts "what every agent is focused on"
+  to a human channel daily; all collective/org actions are logged under
+  `logs/collective/` and `state/org/`.
+
+## Plumbing
+
+- **`maestro global-setup`** (new, idempotent): deep-merges the three collective
+  hooks into `~/.claude/settings.json` (**never clobbering** existing hooks/plugins —
+  same deepMerge+timestamped-backup discipline wundr uses), writes a delimited,
+  idempotent block into `~/.claude/CLAUDE.md`, and writes the `~/.claude/maestro-agent.json`
+  pointer. Run automatically at the end of `init-agent.sh`, by `wundr install` (which
+  already detects + defers to maestro), and standalone. Verified by `maestro doctor`.
+- **Config:** `config/collective.yaml` — `enabled`, `captureModel`, `digestBudgetTokens`,
+  `recencyHalfLifeDays`, `captureOn`, `repoDenylist`, `presence.{heartbeatSec,staleSec}`,
+  `org.{cohort,directorySource}`.
+
+## Anti-bloat invariants (enforced, not aspirational)
+
+1. SessionStart digest is hard-capped at `digestBudgetTokens` (default 1500).
+2. Capture is async, distilled (cheap model), time-boxed, and **fail-open** — it
+   never blocks or slows a session, and never stores raw transcripts.
+3. Recall ranks by relevance × recency-decay × salience and MMR-dedupes before the
+   budget cut.
+4. Presence is one summary line, never a dump.
+5. Everything is opt-out (`enabled: false`) and scoped (repo denylist + info-barriers).
+
+## Module map
+
+| Module | Responsibility |
+|---|---|
+| `lib/collective/config.mjs` | Load `config/collective.yaml` + defaults; agent-root + pointer resolution; denylist check |
+| `lib/collective/cards.mjs` | Memory-card schema, append/read JSONL, salience |
+| `lib/collective/capture.mjs` | Distill a session → cards (pluggable distiller; Haiku default) |
+| `lib/collective/presence.mjs` | Session registry: register/heartbeat/deregister/list/summary/reap |
+| `lib/collective/recall.mjs` | Ranking (relevance×recency×salience), MMR, budgeted digest builder |
+| `lib/org/registry.mjs` | Build/publish self entry; read merged directory |
+| `lib/org/handoff.mjs` | Envelope build/parse, target resolution, send, record |
+| `lib/org/cohort-client.mjs` | Optional cohort API client (publish status / fetch directory) |
+| `scripts/collective/hook-runner.mjs` | Dispatch for the global prime/beat/capture hooks |
+| `scripts/collective/{who,recall}.mjs` | Operator CLIs |
+| `bin/maestro.mjs global-setup` | Idempotent global-config wiring |

package/docs/architecture/continuous-monitoring.md

@@ -0,0 +1,221 @@
+# Continuous Inbound Monitoring & Autonomous Response Architecture
+
+> How the agent watches Slack, WhatsApp, and Gmail continuously and responds autonomously.
+
+---
+
+## Overview
+
+The the agent operating system operates a **continuous monitoring loop** across all communication channels. Unlike the scheduled workflows (morning brief, comms triage) which run at fixed times, the continuous monitor runs **perpetually** — polling channels every 30-120 seconds and dispatching responses based on urgency, classification, and approval rules.
+
+### Two Response Modes
+
+1. **Direct Response** — the agent's main orchestrating Claude Code session handles simple/routine inbound items directly (acknowledgements, status updates, scheduling, routine follow-ups)
+2. **Spawned Session** — For complex inbound tasks that require deep work (research, analysis, document preparation, multi-step coordination), the agent spawns a dedicated Claude Code sub-session that works independently and reports back
+
+```
+┌─────────────────────────────────────────────────────────┐
+│              CONTINUOUS MONITORING LOOP                   │
+│                                                          │
+│  ┌──────────┐  ┌──────────┐  ┌──────────────┐          │
+│  │  Slack    │  │ WhatsApp │  │    Gmail      │          │
+│  │ Monitor  │  │ Monitor  │  │   Monitor     │          │
+│  └────┬─────┘  └────┬─────┘  └──────┬───────┘          │
+│       │              │               │                   │
+│       └──────────────┼───────────────┘                   │
+│                      ▼                                   │
+│           ┌──────────────────┐                           │
+│           │ Inbound          │                           │
+│           │ Dispatcher       │                           │
+│           └────────┬─────────┘                           │
+│                    │                                     │
+│         ┌──────────┼──────────┐                          │
+│         ▼          ▼          ▼                          │
+│    ┌─────────┐ ┌────────┐ ┌─────────┐                   │
+│    │ Simple  │ │ Queue  │ │ Complex │                    │
+│    │ Direct  │ │ for    │ │ Spawn   │                    │
+│    │ Reply   │ │ Review │ │ Session │                    │
+│    └─────────┘ └────────┘ └─────────┘                   │
+│                                                          │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Monitoring Loop Intervals
+
+| Channel  | Poll Interval | Method                  | Scope                              |
+| -------- | ------------- | ----------------------- | ---------------------------------- |
+| Slack    | 60 seconds    | Desktop app observation | Priority channels + DMs + mentions |
+| Gmail    | 120 seconds   | Browser observation     | Unread inbox, priority senders     |
+| WhatsApp | 120 seconds   | Desktop app observation | Business-tagged contacts only      |
+
+These run as **persistent background processes** via launchd, independent of the main Claude Code session.
+
+---
+
+## Inbound Classification
+
+Every inbound message is classified along three dimensions:
+
+### 1. Urgency
+
+| Level        | Criteria                                                     | Response SLA                  |
+| ------------ | ------------------------------------------------------------ | ----------------------------- |
+| **Critical** | From the principal, regulator, or flagged-urgent contact            | < 5 minutes (immediate alert) |
+| **High**     | From investor, board member, acquisition target, senior team | < 30 minutes                  |
+| **Normal**   | From team member, known contact, routine business            | < 2 hours                     |
+| **Low**      | Newsletter, notification, non-actionable                     | Next scheduled triage         |
+
+### 2. Complexity
+
+| Level        | Criteria                                                      | Response Mode                       |
+| ------------ | ------------------------------------------------------------- | ----------------------------------- |
+| **Simple**   | Acknowledgement, yes/no, scheduling, status update            | Direct reply from main session      |
+| **Moderate** | Requires context lookup, short analysis, or coordination      | Direct reply with research          |
+| **Complex**  | Requires deep analysis, document preparation, multi-step work | Spawn dedicated Claude Code session |
+
+### 3. Risk
+
+| Level      | Criteria                                                 | Approval                  |
+| ---------- | -------------------------------------------------------- | ------------------------- |
+| **Low**    | Internal team, routine content                           | Auto-send (pre-approved)  |
+| **Medium** | External known contact, substantive content              | Draft + queue for review  |
+| **High**   | Investor, regulator, board, M&A, financial/legal content | Draft + explicit approval |
+
+---
+
+## Autonomous Response Rules
+
+the agent can respond autonomously (without the principal's approval) to:
+
+### Auto-Respond (Send Immediately, Log All)
+
+- Internal team messages requesting status updates
+- Acknowledgements to known contacts ("Thanks, received — reviewing now")
+- Calendar confirmations and scheduling responses
+- Follow-up chasers for items already approved
+- Internal Slack thread replies continuing approved conversation threads
+
+### Draft-and-Hold (Send After Review)
+
+- First-contact replies to external parties
+- Substantive responses containing analysis or recommendations
+- Any reply that creates a commitment or deadline
+- Messages to contacts classified as investor/board/regulator
+
+### Escalate Immediately (Alert the principal)
+
+- Messages from regulators (the regulator, MAS, FCA, SEC, etc.)
+- Messages flagged as urgent from any channel
+- Messages containing legal threats or compliance issues
+- Messages from acquisition targets or their advisors
+
+---
+
+## Session Spawning
+
+When an inbound item requires complex work, the agent spawns a dedicated Claude Code session:
+
+### When to Spawn
+
+- Research request requiring web searches and analysis (> 5 minutes of work)
+- Document preparation (memo, brief, analysis, board material)
+- Multi-repo investigation (checking code, regulatory docs, strategy docs)
+- Due diligence task on a rollup target
+- Complex email requiring context assembly from multiple sources
+- Any task that would block the main monitoring loop for > 3 minutes
+
+### Spawn Mechanism
+
+```bash
+# the agent spawns a sub-session with a specific task
+claude --dangerously-skip-permissions \
+  -p "You are working for a Maestro agent
+      Task: {task_description}
+      Context: {assembled_context}
+      Deliver output to: {output_path}
+      When complete, write a summary to: {completion_signal_path}" \
+  --output-format text \
+  > logs/sessions/{session_id}.log 2>&1 &
+```
+
+### Session Contract
+
+Each spawned session receives:
+
+- **Task description** — What needs to be done
+- **Context** — Relevant knowledge, conversation history, source material
+- **Output path** — Where to write the deliverable
+- **Completion signal** — File path to write when done (monitored by main session)
+- **Time budget** — Maximum runtime before auto-termination
+- **Scope boundary** — What repos/files the session may access
+
+### Session Types
+
+| Type            | Use Case                        | Time Budget | Example                                                          |
+| --------------- | ------------------------------- | ----------- | ---------------------------------------------------------------- |
+| Quick Research  | Look something up, summarise    | 5 min       | "What's the latest on the regulator AI governance guidelines?"            |
+| Draft Response  | Prepare a reply needing context | 10 min      | Complex email reply needing rollup strategy context              |
+| Analysis        | Deep dive on a topic            | 30 min      | Competitive intelligence report on a new entrant                 |
+| Document Prep   | Create a deliverable            | 60 min      | Board readiness assessment, target briefing                      |
+| Multi-Repo Task | Cross-codebase investigation    | 30 min      | Check the regulator gap status across the regulatory-submission and platform repos |
+
+### Session Lifecycle
+
+```
+Spawn → Execute → Write Output → Signal Completion → Main Session Reviews → Route Output
+```
+
+1. **Spawn**: Main session creates the task with full context
+2. **Execute**: Sub-session works independently
+3. **Output**: Sub-session writes deliverable to `outputs/sessions/{id}/`
+4. **Signal**: Sub-session writes completion marker
+5. **Review**: Main session reads output, verifies quality
+6. **Route**: Main session delivers output (send reply, file memo, update memory, etc.)
+
+---
+
+## Monitoring Process Architecture
+
+### launchd Services
+
+Three persistent monitoring services, each as a launchd daemon:
+
+1. **ai.maestro.monitor.slack** — Slack observation loop
+2. **ai.maestro.monitor.gmail** — Gmail observation loop
+3. **ai.maestro.monitor.whatsapp** — WhatsApp observation loop
+
+Plus one dispatcher:
+
+4. **ai.maestro.dispatcher** — Classifies and routes inbound items
+
+### Main Session Role
+
+The main Claude Code session (the agent) runs continuously and:
+
+- Reads the inbound queue populated by monitors
+- Classifies items by urgency/complexity/risk
+- Handles simple items directly
+- Spawns sessions for complex items
+- Reviews outputs from spawned sessions
+- Manages the response queue
+- Maintains executive memory and state
+
+### Failure Handling
+
+- If a monitor crashes, launchd restarts it automatically
+- If the main session crashes, monitors continue queueing — items are processed on restart
+- Spawned sessions have time budgets — they are killed if they exceed them
+- All inbound items are persisted to disk before processing (no data loss on crash)
+
+---
+
+## Security Considerations
+
+- Monitors are **observe-only** — they cannot send messages
+- Only the main session (or approved spawned sessions) can send
+- All autonomous sends are logged with full content and recipient
+- Rate limits apply even to autonomous responses
+- The emergency stop halts all monitoring and response
+- Session spawning is logged with task description and scope