@cohortapp/agent-sdk 2.3.0

package/scaffold/config/caller-id-map.yaml

@@ -0,0 +1,46 @@
+# Caller ID to user mapping for voice/SMS authorization
+#
+# Used by: sms-handler.mjs, parse-voice-transcript.mjs, user-context-search.py
+# Maps phone numbers, Slack IDs, and emails to user identities with access levels.
+#
+# Access levels:
+#   ceo        — Full access to all paths (memory, knowledge, state, outputs, docs, logs, all interactions)
+#   leadership — Company knowledge + docs + research/briefs + own interaction logs
+#   partner    — Public knowledge + research + own interaction logs
+#   default    — Unknown callers — public company knowledge only (knowledge/sources/)
+#
+# Hot-reloaded every 60 seconds by sms-handler.mjs — no restart needed after edits.
+#
+# Setup: See docs/guides/voice-sms-setup.md for full configuration instructions.
+
+users:
+  # ── Principal (the person this agent reports to) ──────────────────────────
+  # Replace with your principal's details. This entry should have access_level: ceo.
+  principal:
+    name: "Principal Full Name"
+    phone: ["+1XXXXXXXXXX"]
+    whatsapp: ["+1XXXXXXXXXX"]
+    slack_id: "UXXXXXXXXXX"
+    email: "principal@company.com"
+    access_level: ceo
+
+  # ── Leadership / Team ─────────────────────────────────────────────────────
+  # Add team members who should be recognized by the SMS handler and voice parser.
+  # Each entry needs at minimum: name, slack_id, email, and access_level.
+  # Phone numbers are only needed if the person will contact the agent via SMS/voice.
+
+  # example-leader:
+  #   name: "Example Leader"
+  #   phone: []
+  #   slack_id: "UXXXXXXXXXX"
+  #   email: "leader@company.com"
+  #   access_level: leadership
+
+  # ── Partners / External ───────────────────────────────────────────────────
+
+  # example-partner:
+  #   name: "External Partner"
+  #   phone: []
+  #   slack_id: ""
+  #   email: "partner@external.com"
+  #   access_level: partner

package/scaffold/config/collective.yaml

@@ -0,0 +1,49 @@
+# config/collective.yaml — Collective Memory & Org Mesh
+#
+# Controls cross-session global memory, concurrent-session presence, and the
+# org mesh. See docs/architecture/collective-memory-and-org-mesh.md.
+#
+# Every value below is the built-in default (lib/collective/config.mjs DEFAULTS);
+# this file only needs the keys you want to override. Delete it entirely and the
+# defaults apply. Set `enabled: false` to turn the whole layer off.
+
+enabled: true
+
+# --- Capture (write path) -------------------------------------------------
+# Cheap model used to distil a finished session into memory cards. "haiku" maps
+# to the current Haiku via lib/claude-bin; never the agent's main model.
+captureModel: haiku
+# Which Claude Code hook events trigger a capture pass.
+captureOn: [Stop, PreCompact]
+# Skip distillation for trivial sessions (fewer than this many user turns).
+minTurnsToCapture: 2
+# Hard cap on cards distilled from a single session (anti-bloat + cost guard).
+maxCardsPerSession: 12
+# Repos/paths whose sessions must NOT contribute to memory (substring or glob,
+# matched against the session cwd). Client work, secrets, anything ring-fenced.
+# Information-barrier domains are always excluded regardless of this list.
+repoDenylist: []
+
+# --- Recall (read path) ---------------------------------------------------
+# Hard token budget for the SessionStart digest. THE anti-bloat control.
+digestBudgetTokens: 1500
+# Recency half-life (days) for the recall decay term.
+recencyHalfLifeDays: 30
+
+# --- Presence -------------------------------------------------------------
+presence:
+  heartbeatSec: 60      # how often a live session refreshes its heartbeat
+  staleSec: 300         # entries with no heartbeat past this are reaped
+
+# --- Org mesh -------------------------------------------------------------
+org:
+  # Where the human org chart comes from: file (local) | google | slack.
+  directorySource: file
+  # Channel (Slack id / address) the daily org-pulse + handoff mirror post to.
+  pulseChannel: ""
+  # Optional live cross-machine registry. Off by default (file-backed works
+  # without it). Flip enabled:true + fill apiUrl/orgId to publish to cohort.
+  cohort:
+    enabled: false
+    apiUrl: ""          # e.g. https://api.cohortapp.com
+    orgId: ""

package/scaffold/config/company.json

@@ -0,0 +1,20 @@
+{
+  "_doc": "Company identity & context — the single source of truth for WHO the agent works for. Populated by /init-maestro (CLI interview + docs/company-context/ + GitHub-repo analysis). Framework files reference these via {{company.*}} tokens (resolved at load time); generators (charter, backlog, comms) fold the richer fields into company-specific output. See README.md § Company context.",
+  "name": "UNCONFIGURED",
+  "legalName": "",
+  "website": "",
+  "domain": "",
+  "tagline": "",
+  "description": "",
+  "industry": "",
+  "stage": "",
+  "headcount": "",
+  "locations": [],
+  "jurisdictions": [],
+  "products": [],
+  "competitors": [],
+  "strategicPriorities": [],
+  "keyPeople": [],
+  "contextDocs": [],
+  "repos": []
+}

package/scaffold/config/known-agents.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://cohortapp.com/schemas/agent-sdk/known-agents.v1.json",
+  "schema_version": "1",
+  "_comment": "Registry of all AI agents in your organisation. Read by scripts/daemon/classifier.mjs to prevent cross-agent message interception — when a message @-mentions a specific agent's name or Slack ID, only that agent's daemon should respond. Each agent repo holds its own copy of this file. Populate it with your peer agents at init (the /init-maestro wizard can seed it from company context) and edit when peers are added/removed. Each entry has the shape { name, fullName, slackId, role, repo } — e.g. { \"name\": \"Alex\", \"fullName\": \"Alex Chen\", \"slackId\": \"U0XXXXXXX\", \"role\": \"Chief of Staff\", \"repo\": \"alex-ai\" }.",
+  "agents": []
+}

package/scaffold/config/learning.yaml

@@ -0,0 +1,55 @@
+# config/learning.yaml — Self-Learning Loop (WS3)
+#
+# Controls the autonomous skill-authoring loop: after each finished session the
+# agent reviews what it did and may create or patch a Claude Code skill, then
+# prunes stale skills over time. See docs (Hermes integration design §6).
+#
+# Every value below is the built-in default (lib/learning/config.mjs DEFAULTS);
+# this file only needs the keys you want to override. Delete it entirely and the
+# defaults apply. Set `enabled: false` to turn the whole loop off.
+#
+# Fail-open + silent on non-agent machines, exactly like config/collective.yaml.
+
+enabled: true
+
+# --- Reflect (Pass B — self-improvement review) ---------------------------
+# Skip the skill-review pass for trivial sessions (fewer than this many user
+# turns). Pass A (memory cards) still runs at the collective layer's own gate.
+minTurns: 4
+# Model used for the self-improvement review. Never the agent's main model;
+# "sonnet" maps to the current Sonnet via lib/claude-bin.
+reviewModel: sonnet
+
+# --- Nudge counters -------------------------------------------------------
+# When the agent has done a lot of work without capturing a skill, a NUDGE line
+# is added to the review prompt — it raises the prior toward capturing, but never
+# forces a skill (avoids junk). These are the thresholds that trip the nudge.
+nudgeToolUses: 40      # tool-uses since the last skill write
+nudgeSessions: 8       # reflect runs since the last skill write
+
+# --- Lifecycle / curator --------------------------------------------------
+# An agent-authored skill goes active → stale → archived as it sits unused.
+# `last_activity` refreshes whenever the skill's id appears in a transcript.
+# Archiving MOVES the .md to skills/_archive/ (never deletes); pinned skills are
+# exempt from every transition.
+staleDays: 30
+archiveDays: 90
+
+# --- Curator: umbrella consolidation (phase 2) ----------------------------
+# Periodically the skill-curator merges narrowly-overlapping agent-authored
+# skills into ONE class-level umbrella skill, via a single bounded LLM call run
+# as a DETACHED worker (never a nested sub-session). Conservative by design:
+# only genuinely-overlapping siblings merge; unrelated skills are left alone.
+# Absorbed skills are archived (moved to _archive/, dropped from plugin.json,
+# marked absorbed_into the umbrella) — never deleted.
+consolidation:
+  enabled: true        # turn the consolidation pass on/off
+  minSkills: 5         # don't spawn the LLM below this many agent-authored active skills
+  intervalDays: 14     # minimum days between consolidation passes
+  model: sonnet        # reviewer model for the clustering call
+
+# --- Denylist -------------------------------------------------------------
+# Repos/paths whose sessions must NOT feed the learning loop (substring or glob,
+# matched against the session cwd). This EXTENDS the collective repoDenylist —
+# anything ring-fenced from collective memory is ring-fenced here too.
+repoDenylist: []

package/scaffold/config/model-routing.yaml.example

@@ -0,0 +1,104 @@
+# config/model-routing.yaml — Maestro model router, policy v2 (optional, OFF by default)
+#
+# ─────────────────────────────────────────────────────────────────────────────
+# THIS IS AN EXAMPLE. The router is INERT until you copy this file to
+# `config/model-routing.yaml` AND keep `schema_version: 2`. Without an active
+# config the daemon falls back to its historical default: every `claude --print`
+# spawn uses the keychain-resident Max-subscription OAuth token (Anthropic-only).
+#
+# Kill switch (single step, per machine):
+#   - rename config/model-routing.yaml → .disabled, OR
+#   - export MAESTRO_ROUTER_FORCE_ANTHROPIC=1
+# Both revert to Anthropic-only immediately; the env var even wins over a corrupt
+# config (it is honoured inside resolveChain before any rule runs).
+#
+# Models are NOT defined here — the bundled catalog
+# (lib/model-router/catalog/*.yaml in @cohortapp/agent-sdk) is the source of truth
+# for every model's identity, status, context window, $/MTok cost, compat flags,
+# tool-reliability grade, and harness affordances. This file is POLICY only:
+# aliases, data-class rules, the ordered chain rules, and the budget ladder.
+#
+# Validate before activating:  maestro router validate
+# Explain any decision:        maestro router why <item-or-request-json>
+#
+# Full reference: docs/audit/2026-06-10-enterprise/synthesis/SPEC-llm-router.md
+# ─────────────────────────────────────────────────────────────────────────────
+
+schema_version: 2
+
+# ── Aliases ────────────────────────────────────────────────────────────────
+# Friendly names → bundled catalog refs ("provider/model-id"). Cheap third-party
+# rows are listed but are UNREACHABLE until their key exists on this machine
+# (key-absence-as-enforcement) and, for sessions, until probe-ledger grade A.
+aliases:
+  frontier:       anthropic/claude-opus-4-8
+  default:        anthropic/claude-sonnet-4-6
+  fast:           anthropic/claude-haiku-4-5
+  cheap:          deepseek/deepseek-v4-flash    # direct-api only until DEEPSEEK_API_KEY exists
+  cheap-session:  moonshot/kimi-k2.6            # session-host only after grade A + Phase-5 gates
+
+# ── Defaults ─────────────────────────────────────────────────────────────────
+defaults:
+  needs_tool_use_for_sessions: true   # session work defaults to needs_tool_use:true (W5);
+                                      #   rules opt OUT explicitly. Grade-B/C rows are then
+                                      #   structurally unreachable for tool-using sessions.
+  data_class: sensitive               # DENY-BY-DEFAULT: unlabeled work never leaves Anthropic.
+  cache_ttl: 1h                       # cadence-paced traffic amortizes the 2× write over >5-min gaps.
+
+# ── Backends (data/residency policy + credential binding only) ───────────────
+# allowed_data_classes is the COMPLIANCE gate (not a price gate). A request whose
+# data_class is not in this list is denied for that backend (recorded in tried[]).
+backends:
+  anthropic: { allowed_data_classes: [public, internal, sensitive] }
+  deepseek:  { allowed_data_classes: [public] }
+  moonshot:  { allowed_data_classes: [public] }
+
+# ── Routing policy (ordered, first-match, STRICT-validated) ──────────────────
+# Each rule resolves to a candidate CHAIN of aliases/refs; resolveChain gates
+# them in order (status ▸ harness ▸ capability/grade ▸ context ▸ data_class
+# ▸ credential ▸ breaker ▸ budget ladder) and picks the first survivor. The
+# special chain member "rules" is the caller's deterministic fallback as a
+# terminal candidate. Matching is on STRUCTURED METADATA ONLY — message content
+# never reaches the rule engine, so prompt-injection cannot steer routing.
+routing_policy:
+  # Sensitive roles are pinned to the frontier→default Anthropic chain.
+  - match: { agent_role_in: [ceo_pre_pass, audit, decision_writer, regulatory] }
+    chain: [frontier, default]
+    pin: true                         # exempt from the budget degradation ladder below band 100
+
+  # Inbox classification: cheap, tool-less, direct; deterministic rules terminal.
+  - match: { task_class: classify.inbox }
+    harness: direct
+    chain: [fast, cheap, rules]
+    needs_tool_use: false
+
+  # Lookups (gmail/calendar/etc): cheap, tool-less, direct.
+  - match: { task_class: lookup.* }
+    harness: direct
+    chain: [fast, cheap]
+    needs_tool_use: false
+
+  # Public backlog work — eligible for the cheap session host ONCE gated (Phase 5).
+  - match: { source: backlog, data_class: public, priority: normal }
+    chain: [cheap-session, default]
+
+  # Big prompts go to 1M-ctx rows; NEVER fail over into a smaller context window.
+  - match: { token_estimate_gte: 250000 }
+    chain: [default, frontier]
+
+  # Everything else: the default workhorse, fast as the failover tail.
+  - default: true
+    chain: [default, fast]
+
+# ── Budget degradation ladder (a ladder, not a cliff) ────────────────────────
+# Bands come from budget-guard dailyStatus(). pin + priority:critical are exempt
+# below band 100.
+budget_ladder:
+  "75":  { downgrade_tiers: 1 }                # non-pinned chains downgrade one tier
+  "90":  { force_alias: cheap_or_fast }        # cheap/fast lane only
+  "100": { essential_only: true }              # inbox DMs on the cheapest qualifying row; rest DEFER
+
+# ── Safety net + spawn hygiene ───────────────────────────────────────────────
+fallback_to_anthropic: true            # nothing survives the gates → the Anthropic safety net
+strip_attribution_header: true         # don't poison a third-party prompt cache with tooling metadata
+disable_experimental_betas: true       # Anthropic-only betas off when routed off-Anthropic

package/scaffold/config/org.yaml

@@ -0,0 +1,25 @@
+# config/org.yaml — Org enrollment (Cohort shared knowledge plane).
+#
+# Disabled by default. An agent runs fully standalone with this file inert;
+# nothing here phones home until you fill in a base URL + a credential.
+#
+# This is the canonical shape lib/org/client.mjs reads
+# (org.cohort.{enabled,base,orgId,token,trustedSignersPem?}). `enabled` flips
+# true only once `base` AND a credential (`token`) are present — the server,
+# not this file, enforces ACL; the file only points the agent at the endpoint.
+#
+# To enroll, the easy path is the wizard:  maestro setup --only org
+# (it captures the URL + an admin-issued bearer token or a pairing code and
+# rewrites this file). The fields below document the manual route.
+org:
+  cohort:
+    enabled: false          # set true once base + token are configured
+    base: ""                # server origin for the /v1 binding, e.g. https://cohort.internal
+    orgId: ""               # org slug (optional; used by the legacy directory shape)
+    token: ""               # admin-issued bearer token; or leave blank and set
+                            #   COHORT_API_TOKEN / COHORT_TOKEN in .env (kept out of git)
+    # trustedSignersPem:    # optional: pin snapshot signer PEMs the org publishes
+    #   - |
+    #     -----BEGIN PUBLIC KEY-----
+    #     ...
+    #     -----END PUBLIC KEY-----

package/scaffold/config/orgmail.yaml.example

@@ -0,0 +1,19 @@
+# config/orgmail.yaml — workspace email channel (Cohort-hosted mailbox).
+#
+# GATE FILE: the daemon starts the orgmail channel when THIS file exists
+# (copy this example to config/orgmail.yaml). Delete/rename it to disable —
+# that is the field kill switch, no code change needed.
+#
+# Credentials come from config/org.yaml (org.cohort.{base,orgId,token} — the
+# org enrollment). An org admin must have verified a domain and assigned this
+# agent a mailbox in Cohort → Settings → Email first.
+#
+# Inbound rides org RPC polling (no IMAP, no app passwords):
+#   email.inbox (unread) → email.message (bodies) → state/inbox/orgmail/ →
+#   classifier → session → reply via scripts/org/send-orgmail.mjs.
+# mark_read advances the SERVER-side cursor after a clean handoff; there is no
+# local cursor file. Poll override: MAESTRO_ORGMAIL_POLL_MS env var.
+orgmail:
+  enabled: true
+  poll_seconds: 45
+  mark_read: true

package/scaffold/config/recovery.yaml

@@ -0,0 +1,72 @@
+# config/recovery.yaml — Reboot/outage recovery + resource governance (WS4)
+#
+# Tunes how the agent DEGRADES GRACEFULLY under load and RECOVERS from a
+# reboot/power-outage, instead of bricking. Every value below is the built-in
+# default (read from the matching GOV_* / WATCHDOG_* / DAILY_* env var if set);
+# this file documents them and lets the operator override per-agent. Delete it
+# and the defaults apply.
+#
+# Cardinal rule: the ONLY thing that permanently stops this agent is a HUMAN
+# writing .emergency-stop. The watchdog NEVER writes it — it throttles, trims,
+# restarts the daemon, and (last resort) reboots the box, always ending in
+# "the agent is running again."
+
+# --- Resource governor (lib/resource-governor.mjs) ------------------------
+# One admission gate before every Claude sub-session spawn. ADMIT / QUEUE
+# (keep in the in-memory queue, re-derivable from state/queues) / DEFER (leave
+# on disk; the sweep retries — never burns retry budget).
+governor:
+  per_session_mb: 750        # GOV_PER_SESSION_MB — RAM budget heuristic per session
+  ram_fraction: 0.60         # GOV_RAM_FRACTION — share of total RAM for claude sessions
+  freemem_floor: 0.15        # GOV_FREEMEM_FLOOR — DEFER below this fraction of free RAM
+  load_factor: 1.5           # GOV_LOAD_FACTOR — DEFER when 1m loadavg > cpus * this
+  hard_max: 10               # GOV_HARD_MAX — absolute ceiling on concurrent sessions
+  # dynamicMax = clamp(floor(totalmem*ram_fraction / per_session_mb), 1, min(hard_max, cpus))
+  # effectiveMax = min(dynamicMax, throttle.ceiling)   (throttle written by the watchdog)
+
+# --- Memory watchdog (scripts/watchdog/memory-watchdog.sh) ----------------
+# Self-healing tiers. SOFT throttles (writes state/throttle.json, no kills);
+# HARD trims youngest/biggest subagents (spares the oldest "main"); CRITICAL
+# restarts the daemon; repeated CRITICAL failures escalate to a graceful reboot.
+watchdog:
+  sys_soft_percent: 70       # WATCHDOG_SYS_SOFT_PERCENT
+  sys_hard_percent: 80       # WATCHDOG_SYS_HARD_PERCENT
+  critical_percent: 90       # WATCHDOG_CRITICAL_PERCENT
+  claude_soft_percent: 60    # WATCHDOG_SOFT_PERCENT (claude RSS as % of RAM)
+  claude_hard_percent: 75    # WATCHDOG_HARD_PERCENT
+  min_age_seconds: 60        # WATCHDOG_MIN_AGE — never kill a session younger than this
+  throttle_ttl_seconds: 300  # WATCHDOG_THROTTLE_TTL — soft-throttle auto-expiry
+  critical_sustain_runs: 2   # WATCHDOG_CRITICAL_SUSTAIN — consecutive CRITICAL runs before restart
+  restart_fail_limit: 3      # WATCHDOG_RESTART_FAIL_LIMIT — restarts/window before graceful reboot
+  restart_fail_window_seconds: 900  # WATCHDOG_RESTART_FAIL_WINDOW
+
+# --- Rate breaker (lib/rate-guard.mjs) ------------------------------------
+# Shared cross-session 429 / overload circuit breaker with decorrelated-jitter
+# backoff. One file (state/rate-limits/<provider>.json) so all spawn sources
+# back off together.
+rate:
+  provider: anthropic        # MAESTRO_RATE_PROVIDER
+  base_backoff_ms: 1000      # RATE_BASE_BACKOFF_MS
+  max_backoff_ms: 900000     # RATE_MAX_BACKOFF_MS (15 min)
+  backoff_factor: 3          # RATE_BACKOFF_FACTOR
+
+# --- Daily budget cap (lib/budget-guard.mjs) ------------------------------
+# Sums today's cost ledger. One escalating notice at 50/75/90%; at 100% the
+# governor goes essential-only (backlog + cadence deferred; inbox replies
+# continue). Resets at UTC midnight.
+budget:
+  daily_spend_cap_usd: 25    # DAILY_SPEND_CAP_USD
+  daily_iteration_cap: 0     # DAILY_ITERATION_CAP — 0 = no session-count cap
+
+# --- In-flight resume (dispatcher) ----------------------------------------
+# A marker under state/sessions/resume-pending/ lets a reboot resume mid-flight
+# work via `claude --print --resume`. 3 strikes → the item is marked blocked.
+resume:
+  freshness_ms: 21600000     # MAESTRO_RESUME_FRESHNESS_MS (6h) — older markers block instead of resume
+
+# --- Power recovery -------------------------------------------------------
+# Set on the Mac mini so it boots automatically after a power loss:
+#   sudo pmset -a autorestart 1
+# Combined with auto-login + RunAtLoad daemon plists, the agent self-recovers
+# from a full power outage with no human in the loop. `maestro doctor` checks it.
+pmset_autorestart_required: true

package/scaffold/config/secrets.yaml

@@ -0,0 +1,27 @@
+# config/secrets.yaml — secret lifecycle for this agent.
+#
+# Consumed by `maestro secrets <list|sync|rotate>` and lib/secrets/* at runtime.
+# Reads fail OPEN (a provider that errors is skipped, the chain continues);
+# the broker sync fails CLOSED per secret (a name the broker can't serve is not
+# written locally). Values are NEVER logged — logs/audit/secrets.jsonl is
+# names-only. The default below keeps every secret on this box; point `broker`
+# at the org credential broker to pull org-managed secrets on top.
+#
+# provider — the LOCAL store the agent reads from / rotates into:
+#   file     (default) AES-256-GCM-sealed store under state/secrets/.secrets.json,
+#            keyed by a 32-byte master key created on first use. Durable + writable.
+#   env      process.env, READ-ONLY (rotate fails closed — the environment is ambient).
+#   keychain macOS Keychain via `security` (best-effort; inert off-darwin).
+provider: file
+
+# broker — OPTIONAL. Point this at the org credential broker to layer org-managed
+# secrets above the local store. With a broker configured, read precedence is
+# broker > file > env, and `maestro secrets sync` pulls org secrets into the
+# local store. Omit the whole block to stay fully local (the default).
+#
+# broker:
+#   enabled: true                       # default-on whenever this block exists
+#   base_url: "https://cohort.internal/secrets"   # the broker endpoint
+#   token_env: COHORT_API_TOKEN        # name of the .env var holding the bearer token
+#   identity: ""                        # agent id the broker scopes secrets to
+#                                       #   (defaults to MAESTRO_AGENT_ID, else the agent slug)

package/scaffold/config/slack.yaml.example

@@ -0,0 +1,35 @@
+# config/slack.yaml — Slack channel configuration (optional)
+#
+# Present → the daemon's channel bus drives Slack ingestion through the unified
+# adapter (lib/channels/slack/adapter.mjs), which wraps the real Socket Mode
+# client and closes the reaction / thread-context / cc-channel gaps. The legacy
+# launchd socket-mode plist continues to work independently; this file enables
+# the bus-driven path + the opt-in features below.
+#
+# Slack app setup (api.slack.com/apps → your agent's app):
+#   Socket Mode: ON (App-Level Token xapp-… with connections:write).
+#   Event Subscriptions → Bot events:
+#     message.channels, message.groups, message.im, message.mpim, app_mention
+#     reaction_added, reaction_removed              (for reactions, below)
+#   OAuth scopes (Bot Token Scopes):
+#     channels:history, groups:history, im:history, mpim:history,
+#     reactions:read, chat:write
+#   Reinstall the app after changing scopes/subscriptions.
+
+# ── Ingest mode ──────────────────────────────────────────────────────────────
+# "socket" — persistent WebSocket (recommended; realtime, no public endpoint).
+# "relay"  — Railway cloud-relay webhook fan-out.
+# "poll"   — 60s REST polling (fallback only).
+ingest_mode: socket
+
+# ── Reactions ────────────────────────────────────────────────────────────────
+# Keep reaction_added / reaction_removed events. They arrive as kind:"reaction"
+# (the target message text is resolved via conversations.history) and classify
+# as FYI — the agent observes acknowledgements without replying to them.
+reactions: true
+
+# ── CC channels (observe-not-reply) ─────────────────────────────────────────
+# Channel ids the agent should *watch*. Non-@mention messages in these channels
+# arrive as kind:"channel_cc" and are archived (not replied to) by the
+# directed-gate. The agent still replies to @mentions + thread replies.
+cc_channels: []           # e.g. ["C0ABCDE12", "C0FGHIJ34"]

package/scaffold/config/telegram.yaml.example

@@ -0,0 +1,38 @@
+# config/telegram.yaml — Telegram channel configuration (optional)
+#
+# When this file is present, the daemon registers a Telegram channel via grammY
+# in long-polling mode (no public webhook — works behind NAT, runs inside the
+# daemon). grammY is a dynamic import like baileys: the maestro package installs
+# without it. Opt in with `npm i grammy` in your agent repo.
+#
+# Set up the bot:
+#   1. Talk to @BotFather on Telegram → /newbot → choose a name + username.
+#   2. Copy the HTTP API token it gives you (digits:ABC…).
+#   3. Run: node scripts/setup/init-telegram.mjs   (writes TELEGRAM_BOT_TOKEN to
+#      .env, validates via getMe, and activates this gate file)
+#   4. In BotFather → /setprivacy → Disable, if you want the bot to read all
+#      group messages (otherwise it only sees @mentions + replies + commands).
+
+# ── Token ────────────────────────────────────────────────────────────────────
+# The token is read from the TELEGRAM_BOT_TOKEN env var (.env). This field is a
+# reference reminder only — do NOT paste the token here (config is committable).
+token_env: TELEGRAM_BOT_TOKEN
+
+# ── DM pairing (default-deny) ───────────────────────────────────────────────
+# Unknown DM senders are dropped (with a one-time pairing prompt) until paired.
+# Seed allowlisted Telegram user ids here, or pair at runtime:
+#   • the human DMs the bot:  pair <code>
+#   • the code comes from `maestro pair telegram` (or the prompt the bot sends).
+# Paired ids are appended to config/allowlist.yaml under `telegram:`.
+allowlist_seed: []        # e.g. ["987654321"]
+
+# ── CC groups (observe-not-reply) ───────────────────────────────────────────
+# Group chat ids the agent should *watch* — non-@mention messages in these
+# groups arrive as kind:"channel_cc" and are archived (not replied to) by the
+# directed-gate. The agent still replies when @mentioned or directly replied to.
+cc_groups: []             # e.g. ["-1001234567890"]
+
+# ── Voice notes ─────────────────────────────────────────────────────────────
+# Inbound voice notes are downloaded and transcribed (the transcript becomes the
+# message body + a voice_note attachment). Requires OPENAI_API_KEY for STT.
+transcription: true

package/scaffold/config/voice.yaml.example

@@ -0,0 +1,89 @@
+# config/voice.yaml — Maestro voice channel configuration (optional)
+#
+# Activates the OpenAI Realtime voice channel for this agent. When this
+# file is present and the operator has set OPENAI_API_KEY, the daemon
+# will start a voice-handler worker that:
+#   - Accepts inbound Twilio SIP calls (native SIP connector)
+#   - OR accepts WebSocket connections from a browser widget
+#   - Bridges audio to OpenAI's gpt-realtime-2 model
+#   - Honors the same action-classification policy as Slack/Gmail
+#   - Logs the full transcript to logs/voice/sessions/
+#
+# Without this file, voice mode is OFF.
+
+# ── Provider ───────────────────────────────────────────────────────────────
+provider: openai-realtime          # openai-realtime | gemini-live (planned)
+model: gpt-realtime-2              # or gpt-realtime-translate, gpt-realtime-whisper
+voice: cedar                       # cedar | marin | alloy | ash | ballad | coral | echo | sage | shimmer | verse
+
+# ── Audio + VAD ────────────────────────────────────────────────────────────
+input_audio_format: pcm16          # pcm16 | g711_ulaw (for Twilio bridge) | g711_alaw
+output_audio_format: pcm16
+input_audio_transcription:
+  model: gpt-realtime-whisper      # streaming partial-transcript model
+
+turn_detection:
+  type: server_vad                 # server_vad | semantic_vad | null (push-to-talk)
+  threshold: 0.5
+  prefix_padding_ms: 300
+  silence_duration_ms: 500
+
+# ── Session rotation (mitigates long-call latency drift) ───────────────────
+rotation:
+  max_turns: 12
+  max_duration_ms: 240000          # 4 minutes
+  max_p95_latency_ms: 2000
+
+# ── Inbound channels ───────────────────────────────────────────────────────
+inbound:
+  # Native SIP via Twilio Elastic SIP Trunking → OpenAI. Preferred.
+  twilio_sip:
+    enabled: false
+    elastic_sip_trunk: ""          # Twilio trunk SID
+    openai_sip_uri: "sip:YOUR_PROJECT_ID@sip.api.openai.com;transport=tls"
+    inbound_webhook_path: /voice/sip/incoming   # mounted by your HTTP server
+    caller_id_allowlist: []        # E.164 numbers permitted to reach this agent
+
+  # Legacy Twilio Media Streams bridge (TwiML <Connect><Stream>).
+  twilio_media_streams:
+    enabled: false
+    stream_path: /voice/stream
+    voice_webhook_path: /voice/incoming
+    twiml_status_callback_path: /voice/status
+
+  # Direct browser WebSocket (e.g. a control-panel widget).
+  browser_ws:
+    enabled: false
+    path: /voice/browser
+    ephemeral_token_path: /voice/token   # mints client_secret for the browser
+
+# ── Tool bridge ────────────────────────────────────────────────────────────
+tools:
+  # Which maestro actions are exposed as voice tools.
+  access_level: voice              # uses lib/tool-definitions.js access tier
+  include: []                      # if non-empty, restrict to these names
+  exclude:                         # explicitly hide these from voice surfaces
+    - wire_transfer
+    - delete_repository
+  # Voice-specific guardrails:
+  high_risk_requires_verbal_confirm: true
+  audit_log_path: logs/voice/tool-calls.jsonl
+
+# ── Audit + persistence ────────────────────────────────────────────────────
+audit:
+  transcript_dir: logs/voice/sessions
+  audio_capture: false             # set true to also save WAV files (large)
+  redact_pii_patterns:
+    - '\b\d{3}-\d{2}-\d{4}\b'       # SSN
+    - '\b\d{16}\b'                  # 16-digit card
+
+# ── Voice identity ─────────────────────────────────────────────────────────
+identity:
+  # Override the agent's default identity for the voice surface (optional).
+  # name and role default to config/agent.json firstName + title.
+  custom_instructions: ""
+  voice_mode_appendix: |
+    Speak briefly and naturally — typically 1-2 sentences before
+    pausing for the user. When invoking high-risk actions, read back
+    the key parameters out loud and obtain explicit confirmation in
+    the SAME turn before proceeding.

package/scaffold/config/whatsapp.yaml.example

@@ -0,0 +1,39 @@
+# config/whatsapp.yaml — WhatsApp channel configuration (optional)
+#
+# When this file is present, the daemon registers a WhatsApp channel
+# using the chosen transport.
+
+# ── Transport ──────────────────────────────────────────────────────────────
+# "twilio"  — WhatsApp Business API via Twilio (production-grade, paid)
+# "baileys" — Personal-account WhatsApp Web (free, full media support,
+#             violates WhatsApp ToS for business use — use only for
+#             sole-proprietor / personal-account agents)
+transport: twilio
+
+# ── Twilio (when transport: twilio) ────────────────────────────────────────
+twilio:
+  # The sender phone in E.164 format (e.g. "+14155238886" for the sandbox).
+  from_number: ""
+  # Templated messages need pre-approved templates; the framework only
+  # supports free-form replies inside the 24-hour customer-service window.
+
+# ── Baileys (when transport: baileys) ──────────────────────────────────────
+baileys:
+  # Where Baileys persists auth state. Lose this and you re-scan the QR.
+  auth_dir: state/whatsapp/auth
+  # Voice note transcription. Wire to a Whisper helper or
+  # gpt-realtime-whisper-backed function. Stub provider name resolves
+  # at daemon startup.
+  transcribe_voice_notes_via: whisper-1   # or "gpt-realtime-whisper" | "none"
+
+# ── Common ─────────────────────────────────────────────────────────────────
+peer_allowlist: []     # E.164 phone numbers permitted to converse with the agent
+group_chat_allowlist: []  # Baileys group JIDs the agent is allowed to listen in
+
+# Where outbound voice notes are cached before being sent (for retry / audit).
+outbound_audio_cache: state/whatsapp/outbound
+
+# When inbound voice notes arrive, also save the original audio file
+# alongside the transcript so transcription errors can be diagnosed later.
+keep_audio_files: true
+audio_dir: state/whatsapp/audio