switchroom 0.17.6 → 0.18.3

package/bin/workspace-dynamic-hook.sh

@@ -10,14 +10,13 @@
 # Configuration is via env vars (set at start.sh time):
 #
 #   SWITCHROOM_AGENT_NAME       - The agent name (required, set in start.sh)
-#   SWITCHROOM_INJECT_ON_CHANGE - When "1", enables inject-on-change
-#                                 semantics: content is only emitted when the
-#                                 session_id changes or file content changes.
-#                                 When "0" or unset (legacy mode), content is
-#                                 emitted every turn as before (full emit).
-#                                 Default in new agents is "1" (set by
-#                                 scaffold.ts when inject_on_change is true,
-#                                 the default).
+#   SWITCHROOM_INJECT_ON_CHANGE - Inject-on-change semantics are the default:
+#                                 content is only emitted when the session_id
+#                                 changes or file content changes. Set to "0"
+#                                 to opt out and emit every turn (legacy full
+#                                 emit) — scaffold.ts threads this negation
+#                                 only when an agent sets
+#                                 channels.telegram.inject_on_change: false.
 #
 # Failure modes (all silent — workspace injection must never block the turn):
 #   - switchroom CLI missing  → exit 0 with no output
@@ -29,7 +28,7 @@
 set -u
 
 AGENT_NAME="${SWITCHROOM_AGENT_NAME:-}"
-INJECT_ON_CHANGE="${SWITCHROOM_INJECT_ON_CHANGE:-0}"
+INJECT_ON_CHANGE="${SWITCHROOM_INJECT_ON_CHANGE:-1}"
 
 if [ -z "$AGENT_NAME" ]; then
   exit 0
@@ -43,7 +42,7 @@ fi
 # Inject-on-change: read session_id from stdin JSON (when enabled)
 # ---------------------------------------------------------------------------
 SESSION_ID=""
-if [ "$INJECT_ON_CHANGE" = "1" ]; then
+if [ "$INJECT_ON_CHANGE" != "0" ]; then
   # Read stdin (non-blocking: if no stdin supplied in tests, just skip).
   if ! [ -t 0 ]; then
     STDIN_JSON=$(cat 2>/dev/null || true)
@@ -118,7 +117,7 @@ if [ -f "$BODY_FILE" ]; then
     # In inject-on-change mode, also check the session-state file — if the
     # session_id matches the last-emitted session AND the hash matches, we
     # can suppress entirely (model already has this content in context).
-    if [ "$INJECT_ON_CHANGE" = "1" ] && [ -n "$SESSION_ID" ]; then
+    if [ "$INJECT_ON_CHANGE" != "0" ] && [ -n "$SESSION_ID" ]; then
       SESSION_STATE_DIR="${TELEGRAM_STATE_DIR:-${HOME:-/tmp}/.claude/switchroom-hookcache}/.hook-state"
       SESSION_STATE_FILE="$SESSION_STATE_DIR/ws-dynamic.$SESSION_ID"
       if [ -f "$SESSION_STATE_FILE" ]; then
@@ -201,7 +200,7 @@ _ws_record_session_state() {
 if [ -n "$NEW_HASH" ] && [ "$NEW_HASH" = "$OLD_HASH" ] && [ -f "$BODY_FILE" ]; then
   # Content unchanged since last render. In inject-on-change mode, check if
   # we already injected this content in the current session — if so, suppress.
-  if [ "$INJECT_ON_CHANGE" = "1" ] && [ -n "$SESSION_ID" ]; then
+  if [ "$INJECT_ON_CHANGE" != "0" ] && [ -n "$SESSION_ID" ]; then
     SESSION_STATE_DIR="${TELEGRAM_STATE_DIR:-${HOME:-/tmp}/.claude/switchroom-hookcache}/.hook-state"
     SESSION_STATE_FILE="$SESSION_STATE_DIR/ws-dynamic.$SESSION_ID"
     if [ -f "$SESSION_STATE_FILE" ]; then
@@ -222,7 +221,7 @@ else
   if [ -n "$NEW_HASH" ]; then
     printf '%s\n' "$NEW_HASH" > "$CACHE_FILE" 2>/dev/null || true
     printf '%s\n' "$WS_DYNAMIC" > "$BODY_FILE" 2>/dev/null || true
-    if [ "$INJECT_ON_CHANGE" = "1" ] && [ -n "$SESSION_ID" ]; then
+    if [ "$INJECT_ON_CHANGE" != "0" ] && [ -n "$SESSION_ID" ]; then
       _ws_record_session_state "$NEW_HASH" "$SESSION_ID"
     fi
   fi

package/dist/agent-scheduler/index.js

@@ -11070,8 +11070,35 @@ var AgentMemorySchema = exports_external.object({
   auto_recall: exports_external.boolean().default(true).describe("Auto-search memories before each response"),
   file: exports_external.boolean().default(true).describe("Maintain a curated workspace MEMORY.md file (seeded once, " + "auto-loaded every turn). Set false for hindsight-only memory: " + "the file is not seeded or re-created, so once migrated into " + "Hindsight and deleted it stays gone. Recall + directives carry " + "the memory instead. Cascade: override (per-agent wins over default)."),
   isolation: exports_external.enum(["default", "strict"]).default("default").describe("strict = never shared cross-agent, default = eligible for reflect"),
-  bank_mission: exports_external.string().optional().describe("Bank-level mission statement used during recall to contextualize results"),
-  retain_mission: exports_external.string().optional().describe("Instructions for the fact extraction LLM during retain"),
+  bank_mission: exports_external.string().optional().describe("Bank-level mission statement used during recall to contextualize " + "results. NOTE: this is an alias for the Hindsight engine's " + "`reflect_mission` field (verified live: switchroom's bank_mission " + "lands in `config.reflect_mission`). Prefer `reflect_mission` going " + "forward; `bank_mission` is retained for back-compat. If both are " + "set, `reflect_mission` wins. Cascade: override."),
+  reflect_mission: exports_external.string().optional().describe("Mission/context steering Hindsight Reflect operations (the bank's " + "'who am I / what matters' framing applied during recall). The " + "engine-accurate name for what `bank_mission` sets. Cascade: override."),
+  retain_mission: exports_external.string().optional().describe("Instructions for the fact extraction LLM during retain. Cascade: override."),
+  mental_models: exports_external.array(exports_external.object({
+    name: exports_external.string().min(1).describe("Stable model name (identity key for idempotent ensure). Two " + "declarations with the same name in one agent are rejected."),
+    source_query: exports_external.string().min(1).max(2000).describe("The reflection query the model answers, semantically " + "refreshed from the bank's content. Capped at 2000 chars — a " + "standing reflection query, not a document; the ceiling also " + "bounds what an agent-proposed model can smuggle past the " + "operator approval card."),
+    refresh_after_consolidation: exports_external.boolean().optional().describe("Refresh this model after each consolidation. Defaults OFF — " + "refresh adds bounded background model-spend + timeout risk " + "(RFC Phase 5), so it is opt-in per model."),
+    max_tokens: exports_external.number().int().positive().max(8192).optional().describe("Cap on the synthesized model's token size. Upper-bounded at " + "8192 — a mental model is a standing summary, not a corpus; the " + "ceiling also caps what an agent-proposed model can request.")
+  })).superRefine((models, ctx) => {
+    const seen = new Set;
+    for (let i = 0;i < models.length; i++) {
+      const key = models[i].name;
+      if (seen.has(key)) {
+        ctx.addIssue({
+          code: exports_external.ZodIssueCode.custom,
+          path: [i, "name"],
+          message: `duplicate mental_models name "${key}" — model names must be ` + `unique within an agent (they are the idempotent-ensure key)`
+        });
+      }
+      seen.add(key);
+    }
+  }).optional().describe("Operator-declared, per-specialist Hindsight mental models (RFC " + "Phase 5). Named, opt-in curated reflections this agent's bank should " + "carry — e.g. a coach's 'training-plan-state' or a lawyer's " + "'open-matters'. Ensured idempotently at scaffold/reconcile: NOTHING " + "is created unless declared here (zero declarations = zero models, " + "matching post-#2447 behaviour), and no fixed identity model is " + "reintroduced — 'who the user is' stays owned by dedicated profile " + "banks (users.*.profile_bank), never a per-agent model. Per-agent " + "ONLY: intentionally not accepted at the defaults/profile tier, so a " + "model can never be fleet-seeded — each specialist opts in on its own " + "(the invariant-clean inverse of the retired blind auto-seeding)."),
+  observations_mission: exports_external.string().optional().describe("Steers what the observation-consolidation LLM synthesises from raw " + "facts (the higher-order 'what patterns matter' lens). Cascade: override."),
+  disposition: exports_external.object({
+    skepticism: exports_external.number().int().min(1).max(5).optional().describe("How much the bank doubts unverified claims (1-5; engine default 3)."),
+    literalism: exports_external.number().int().min(1).max(5).optional().describe("How literally the bank reads statements vs inferring intent (1-5; engine default 3)."),
+    empathy: exports_external.number().int().min(1).max(5).optional().describe("How much the bank weights emotional/relational context (1-5; engine default 3).")
+  }).optional().describe("Personality traits (1-5 each) steering how this bank frames recall, " + "reflect, and observation synthesis — a coach leans empathy-high, a " + "lawyer/analyst leans skepticism/literalism-high. Maps to the engine's " + "flat `disposition_skepticism`/`_literalism`/`_empathy` fields. " + "Cascade: per-key merge (an agent overrides individual traits and " + "inherits the rest, matching `recall`)."),
+  directive_capture_nudge: exports_external.boolean().optional().describe("Deterministic directive-capture nudge (issue #2848 Stage B). When " + "on (switchroom default true — Stage A measured a ~55% miss rate on " + "durable corrections), the auto-recall hook regex-detects correction " + '/ standing-rule-shaped inbound ("always/never …", "from now on …", ' + `"stop doing …", a stated preference, "that's wrong, it's …") and ` + "appends a terse advisory to the turn's context telling the model to " + "persist the rule with mcp__hindsight__create_directive if it IS " + "durable. Detection is pure regex — the model does the judgment " + "in-session and calls create_directive itself (no model callsite, no " + "silent hook-side write). Set false to disable per-agent. " + "Cascade: override (per-agent wins over default)."),
   recall: exports_external.object({
     max_memories: exports_external.number().int().min(0).optional().describe("Cap on the number of memories injected into the prompt by " + "auto-recall, regardless of token budget. Plugin default is 12. " + "0 disables the cap (all memories Hindsight returns are injected)."),
     cache_ttl_secs: exports_external.number().int().min(0).optional().describe("Per-session recall cache TTL in seconds. When > 0, identical " + "(prompt, bank) within the same session reuse the cached recall " + "result instead of round-tripping to Hindsight. 0 disables. " + "Default is 600 (10 min) for switchroom-managed agents."),
@@ -11081,7 +11108,11 @@ var AgentMemorySchema = exports_external.object({
     sender_banks: exports_external.record(exports_external.string(), exports_external.string()).optional().describe("Per-speaker recall routing: a map of Telegram sender → extra " + "recall bank. When a message arrives, the agent also recalls the " + "speaker's bank (matched by Telegram username — a leading @ is " + "optional — or numeric user_id), merged " + "into its own results — so each trusted user gets their own " + "profile context. Additive recall scoping within the single " + "tenant: never an access boundary (who may drive an agent stays " + "the per-agent user assignment in `access.allowFrom`). Author the " + "banks via `switchroom memory profile`."),
     skip_trivial: exports_external.boolean().optional().describe("Skip recall on plausibly-stateless trivial turns (time/date/" + "greeting). Switchroom default true — saves the recall arm + " + "injected tokens on turns that never need memory, guarded so it " + "never skips a turn that references user/project/session state. " + "Set false to always run recall."),
     topic_filter_mode: exports_external.enum(["soft-preamble", "hard-filter"]).optional().describe("Supergroup-mode cross-topic memory behaviour. Default " + "(unset) → soft-preamble: recall returns memories from all " + "topics, and a 'Current topic: …' preamble tells the model " + "to self-scope. hard-filter: drop any recalled memory whose " + "metadata.thread_id differs from the active inbound's topic. " + "Flip to hard-filter when the recall_log shows binding " + "failures (model surfacing the right memory but applying " + "it to the wrong topic).")
-  }).optional().describe("Auto-recall tuning knobs")
+  }).optional().describe("Auto-recall tuning knobs"),
+  retain: exports_external.object({
+    every_n_turns: exports_external.number().int().min(1).optional().describe("How often the Stop hook fires auto-retention, in turns. The " + "vendor plugin default is 10 (a short session can end before " + "retention ever fires); switchroom's scaffold default is 3. " + "Lower = more frequent, smaller retains + tighter crash " + "durability (at 1, every turn is retained before a restart can " + "lose it); higher = fewer, larger retains + less LLM churn. " + "Raised from the historical 1 to 3 because the local reasoning " + "consolidation model (Ollama gpt-oss-20b) ran away on the large " + "overlapping every-turn payloads. Set to 1 for the old " + "every-turn crash-durability guarantee. Min 1. Cascade: " + "per-field merge (agent wins over default)."),
+    overlap_turns: exports_external.number().int().min(0).optional().describe("Extra recent turns included in each chunked retain window on " + "top of `every_n_turns`, so window = overlap_turns + " + "every_n_turns recent turns. Vendor default is 2; switchroom's " + "scaffold default is 1 (smaller payloads for the local " + "reasoning consolidation model). Higher = more redundant " + "context re-sent per fire. Min 0. Cascade: per-field merge.")
+  }).optional().describe("Auto-retain (Stop-hook consolidation) cadence knobs")
 }).optional();
 var HookEntrySchema = exports_external.object({
   command: exports_external.string().describe("Shell command to run. Supports ${CLAUDE_CONFIG_DIR} and ${CLAUDE_PLUGIN_ROOT} substitution."),
@@ -11259,6 +11290,21 @@ var LiteLLMConfigSchema = exports_external.object({
   small_fast_model: exports_external.string().optional().describe("Model id exported as ANTHROPIC_SMALL_FAST_MODEL for the claude CLI's " + "background/fast lane, e.g. 'claude-haiku-4-5-20251001'."),
   tags: exports_external.record(exports_external.string(), exports_external.string()).optional().describe("Extra key/value metadata tags attached to the provisioned LiteLLM " + "virtual key. Merged per-key across cascade layers (agent wins).")
 }).optional().describe("LiteLLM routing config — opt-in per-agent virtual-key auto-provisioning " + "+ routing env. Default OFF. See LiteLLMConfigSchema doc for the full flow.");
+var HindsightPerOpLlmSchema = exports_external.object({
+  model: exports_external.string().min(1).optional().describe("Per-op model (upstream `HINDSIGHT_API_<OP>_LLM_MODEL`). Absent → " + "inherit the global `hindsight.llm.model`."),
+  provider: exports_external.string().min(1).optional().describe("Per-op provider (upstream `HINDSIGHT_API_<OP>_LLM_PROVIDER`). " + "Absent → inherit the global `hindsight.llm.provider`."),
+  base_url: exports_external.string().min(1).optional().describe("Per-op base URL (upstream `HINDSIGHT_API_<OP>_LLM_BASE_URL`). " + "Optional passthrough; absent → inherit the global."),
+  api_key: exports_external.string().min(1).optional().describe("Per-op API key (upstream `HINDSIGHT_API_<OP>_LLM_API_KEY`). Literal " + "or `vault:` reference. Optional passthrough; absent → inherit global.")
+}).describe("Per-operation LLM override. Every field optional; an unset field (or " + "an omitted op block) inherits the global `hindsight.llm.*`, which is " + "already the engine's fallback — switchroom emits only the vars set.");
+var HindsightConfigSchema = exports_external.object({
+  llm: exports_external.object({
+    provider: exports_external.string().min(1).optional().describe("Hindsight LLM provider (upstream `HINDSIGHT_API_LLM_PROVIDER`). " + "Defaults to `claude-code` (subscription-honest, broker-fed OAuth). " + "Any litellm-routable provider the upstream image supports is valid. " + "Serves as the GLOBAL default for every op absent a per-op override."),
+    model: exports_external.string().min(1).optional().describe("Hindsight LLM model (upstream `HINDSIGHT_API_LLM_MODEL`). Defaults " + "to HINDSIGHT_DEFAULT_MODEL. Any model your LiteLLM proxy can route " + "is valid, e.g. `openrouter/z-ai/glm-5.2` when routing through the " + "fleet proxy. With provider=claude-code this value is ALSO exported " + "as `ANTHROPIC_MODEL` to the claude subprocess. Serves as the GLOBAL " + "default for every op absent a per-op override."),
+    retain: HindsightPerOpLlmSchema.optional().describe("Per-op override for the `retain` LLM op (memory ingestion). Emits " + "`HINDSIGHT_API_RETAIN_LLM_*`. Absent → uses the global model/provider."),
+    reflect: HindsightPerOpLlmSchema.optional().describe("Per-op override for the `reflect` LLM op (synthesis / mental-model " + "refresh). Emits `HINDSIGHT_API_REFLECT_LLM_*`. Absent → uses global."),
+    consolidation: HindsightPerOpLlmSchema.optional().describe("Per-op override for the `consolidation` LLM op (background memory " + "merge). Emits `HINDSIGHT_API_CONSOLIDATION_LLM_*`. Absent → global.")
+  }).optional().describe("LLM knob for the hindsight container. The flat `provider`/`model` set " + "the global default (backward-compatible); optional `retain`/`reflect`/" + "`consolidation` blocks override individual ops. All fields optional; " + "unset fields fall back to the hard-coded defaults.")
+});
 var MicrosoftWorkspaceConfigSchema = exports_external.object({
   microsoft_client_id: exports_external.string().min(1).optional().describe("Microsoft OAuth application (client) ID from Entra portal " + "(literal string or vault reference e.g. " + "'vault:microsoft-oauth-client-id'). OPTIONAL — omit it to use " + "switchroom's shipped default Microsoft app (zero-config). " + "Set it only to bring your own Entra app (BYO)."),
   microsoft_client_secret: exports_external.string().min(1).optional().describe("Microsoft OAuth client secret. Optional — public-client apps " + "(Mobile + Desktop platform with 'Allow public client flows' " + "enabled) work without a secret; confidential clients pass " + "one. Either literal or vault reference e.g. " + "'vault:microsoft-oauth-client-secret'."),
@@ -11336,6 +11382,7 @@ var profileFields = {
     auto_recall: exports_external.boolean().optional(),
     file: exports_external.boolean().optional(),
     isolation: exports_external.enum(["default", "strict"]).optional(),
+    directive_capture_nudge: exports_external.boolean().optional(),
     recall: exports_external.object({
       max_memories: exports_external.number().int().min(0).optional(),
       cache_ttl_secs: exports_external.number().int().min(0).optional(),
@@ -11506,6 +11553,7 @@ var MemoryBackendConfigSchema = exports_external.object({
   config: exports_external.object({
     provider: exports_external.string().default("ollama").describe("Embedding provider (ollama, openai, anthropic)"),
     model: exports_external.string().optional().describe("Embedding model (e.g., 'nomic-embed-text')"),
+    llm_model: exports_external.string().optional().describe("LiteLLM model name for Hindsight's LLM ops (retain/reflect/" + "consolidation) when the top-level `litellm.enabled` carve-out is " + "on. Defaults to a cheap OpenRouter model (routed via LiteLLM's " + "model-mapped path, not the Anthropic OAuth pass-through) to keep " + "background memory-op cost off the Claude subscription quota. Set " + "to a `claude-*` model name to route it back through the OAuth " + "pass-through instead. Has no effect when litellm is disabled."),
     api_key: exports_external.string().optional().describe("API key or vault reference for embedding provider"),
     docker_service: exports_external.boolean().default(true).describe("Whether to include Hindsight in docker-compose"),
     url: exports_external.string().url("Hindsight URL must be a valid URL (no shell-special characters)").optional().describe("Hindsight MCP endpoint URL (e.g., http://localhost:18888/mcp/). Defaults to http://localhost:8888/mcp/.")
@@ -11583,6 +11631,7 @@ var SwitchroomConfigSchema = exports_external.object({
   telegram: TelegramConfigSchema,
   release: ReleaseBlock.optional().describe("Fleet-wide default release-channel pin / pointer for the update " + "flow. Either `channel` (dev|rc|latest) or `pin` (sha-<hex>|v<semver>) " + "— mutually exclusive. Per-agent `release` REPLACES this entirely."),
   memory: MemoryBackendConfigSchema.optional(),
+  hindsight: HindsightConfigSchema.optional().describe("Fleet-singleton Hindsight (memory backend) configuration. Currently " + "just the LLM knob (provider + model) used for retain/reflect/" + "consolidation. Both fields optional; when unset the container falls " + "back to provider=claude-code + the hard-coded HINDSIGHT_DEFAULT_MODEL " + "so nothing changes for operators who don't set it. Read at container " + "launch by startHindsight() (src/setup/hindsight.ts) — takes effect on " + "the next `switchroom apply` / `memory setup --recreate`."),
   vault: VaultConfigSchema.optional(),
   auth: exports_external.object({
     active: exports_external.string().min(1).optional().describe("Fleet-wide active Anthropic account label. Every agent without " + "an explicit `agent.auth.override` uses this account. See " + "docs/auth.md for the full model. Set by `switchroom auth use <label>`."),
@@ -11979,6 +12028,16 @@ function mergeAgentConfig(defaultsIn, agentIn) {
         continue;
       if (k === "recall" && base.recall && typeof v === "object" && v !== null && !Array.isArray(v)) {
         combined[k] = { ...base.recall, ...v };
+      } else if (k === "retain" && base.retain && typeof v === "object" && v !== null && !Array.isArray(v)) {
+        combined[k] = {
+          ...base.retain,
+          ...v
+        };
+      } else if (k === "disposition" && base.disposition && typeof v === "object" && v !== null && !Array.isArray(v)) {
+        combined[k] = {
+          ...base.disposition,
+          ...v
+        };
       } else {
         combined[k] = v;
       }
@@ -12426,7 +12485,8 @@ function dispatchAsInbound(entry, options, dispatcher) {
       schedule_index: String(entry.scheduleIndex),
       prompt_key: entry.promptKey,
       ...options.session === "cron" ? { session: "cron" } : {},
-      ...options.session === "cron" && options.model ? { model: options.model } : {}
+      ...options.session === "cron" && options.model ? { model: options.model } : {},
+      ...options.replayFireMs !== undefined ? { replay_fire_ms: String(options.replayFireMs) } : {}
     }
   };
   const delivered = dispatcher.sendToAgent(entry.agent, message);
@@ -14962,7 +15022,7 @@ async function main() {
             continue;
           }
           const threadId = resolveEntryThreadId(m.entry, channel);
-          const result = dispatchAsInbound(m.entry, { chatId: channel.chatId, threadId }, dispatcher);
+          const result = dispatchAsInbound(m.entry, { chatId: channel.chatId, threadId, replayFireMs: m.expectedFireMs }, dispatcher);
           sink.recordFire({
             agent: m.entry.agent,
             scheduleIndex: m.entry.scheduleIndex,