@jungjaehoon/mama-os 0.20.1 → 0.22.0

package/dist/operator/operator-interfaces.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Generic operator mechanism interfaces (PUBLIC-SAFE).
+ *
+ * Extracted from Kagemusha's `AgentAwarenessOptions` injection seam
+ * (~/project/mama-suite/apps/kagemusha/src/runtime/agent-awareness.ts:199-237).
+ * Kagemusha's operator is already dependency-injected; these interfaces genericize the
+ * Kagemusha-typed deps so MAMA OS can supply its own implementations.
+ *
+ * HARD RULE: no personal/business data here. Channel rosters, personas, prompts, Trello,
+ * schedule times, tokens are INJECTED via implementations/config, never in this source.
+ * See memory: project_kagemusha_port_privacy_boundary.
+ */
+/**
+ * A raw channel event pulled from the delta source.
+ * Ports Kagemusha `DbChannelMessage` (db/channel-message-repo.ts:3-11) - generic, no platform.
+ */
+export interface OperatorChannelEvent {
+    id: number;
+    /** logical channel kind key, e.g. "discord" | "slack" | "telegram" (impl-defined) */
+    channel: string;
+    /** opaque per-channel conversation id */
+    channelId: string;
+    /** opaque author id */
+    userId: string;
+    role: 'user' | 'assistant';
+    content: string;
+    createdAt: number;
+    /** stable provenance id when the source is connector_event_index (TEXT PK); optional. */
+    eventIndexId?: string;
+}
+/**
+ * Per-channel delta source: "only-new-since-cursor", at-least-once.
+ * Ports Kagemusha `ChannelMessageRepository` (db/channel-message-repo.ts:18,25,219).
+ */
+export interface ChannelDeltaRepo {
+    /** Contiguous, ordered events with id > sinceId, excluding the given channels. */
+    getNewSince(sinceId: number, excludeChannels?: string[], limit?: number): OperatorChannelEvent[];
+    record(channel: string, channelId: string, userId: string, role: 'user' | 'assistant', content: string, options?: {
+        createdAt?: number;
+    }): OperatorChannelEvent;
+}
+/** Ports Kagemusha `KagemushaAgentResponse`. */
+export interface OperatorAgentResponse {
+    text: string;
+    isError?: boolean;
+}
+/**
+ * The single serial agent (queue -> one prompt in flight).
+ * Ports Kagemusha `KagemushaAgentLoop.chat` (agent/agent-loop.ts:269).
+ */
+export interface OperatorAgentLoop {
+    chat(userMessage: string, callbacks?: unknown, channel?: string): Promise<OperatorAgentResponse>;
+}
+/**
+ * Memory port - bound to mama-core in the MAMA implementation (Task 3).
+ * The operator delegates ONLY memory here; operational state stays operator-owned.
+ */
+export interface OperatorMemoryPort {
+    /** Persist an operational decision/lesson. Binds to mama-core `save`/`saveMemory`. */
+    save(input: {
+        topic: string;
+        content: string;
+        scopes?: unknown;
+    }): Promise<{
+        id: string;
+    } | void>;
+    /** Semantic recall. Binds to mama-core `recallMemory`/`suggest`. */
+    recall(query: string, opts?: {
+        limit?: number;
+    }): Promise<ReadonlyArray<{
+        topic: string;
+        content: string;
+        similarity?: number;
+    }>>;
+}
+/** Operator-owned task. Ports Kagemusha `Task` (runtime/task-store.ts:3). */
+export interface OperatorTask {
+    id: number;
+    title: string;
+    status: string;
+    priority: string;
+    deadline: number | null;
+    createdAt: number;
+    updatedAt: number;
+}
+/** Task source - operator-owned operational state. */
+export interface TaskSource {
+    getTasks(): OperatorTask[];
+}
+/** Ports Kagemusha `ReportSlotSnapshot` (runtime/report-fallback.ts:1). */
+export interface ReportSlotSnapshot {
+    html: string;
+    updatedAt: number;
+}
+/** Report sink - the deterministic report board. */
+export interface ReportSink {
+    getReportSlots(): Record<string, ReportSlotSnapshot>;
+    setReportSlots(slots: Record<string, string>): void;
+}
+/**
+ * Output sink - generic outbound send. The personal destination (which chat/room) is
+ * bound inside the implementation, never here. Ports Kagemusha `sendTelegram`.
+ */
+export interface OutputSink {
+    send(text: string): Promise<void>;
+}
+/**
+ * Operator schedule/timing config. Values are loaded from `~/.mama/operator/*.json`, NOT
+ * hardcoded in source. Ports Kagemusha `KagemushaDigestScheduleConfig` (config/ai-config.ts:12).
+ */
+export interface OperatorScheduleConfig {
+    /** proactive delta-drain interval */
+    deltaDigestIntervalMinutes: number;
+    /** local hours (0-23) at which a full report fires */
+    fullReportHours: number[];
+    /** hourly task-reminder window */
+    reminderStartHour: number;
+    reminderEndHour: number;
+}
+/**
+ * The full injection surface for the operator mechanism.
+ * Genericizes Kagemusha `AgentAwarenessOptions` - every field is injected; the mechanism
+ * hardcodes nothing personal.
+ */
+export interface OperatorRuntimeDeps {
+    agentLoop: OperatorAgentLoop;
+    channelRepo: ChannelDeltaRepo;
+    memory: OperatorMemoryPort | null;
+    tasks: TaskSource;
+    reports: ReportSink | null;
+    output: OutputSink;
+    schedule: OperatorScheduleConfig;
+    /** logical channel kinds the delta drain excludes (e.g. the reactive owner-DM channel) */
+    excludeFromDelta?: string[];
+}
+//# sourceMappingURL=operator-interfaces.d.ts.map

package/dist/operator/operator-interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator-interfaces.d.ts","sourceRoot":"","sources":["../../src/operator/operator-interfaces.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,qFAAqF;IACrF,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,yFAAyF;IACzF,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kFAAkF;IAClF,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,EAAE,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,oBAAoB,EAAE,CAAC;IACjG,MAAM,CACJ,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GAAG,WAAW,EAC1B,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAC/B,oBAAoB,CAAC;CACzB;AAED,gDAAgD;AAChD,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,CACF,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,OAAO,EACnB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,sFAAsF;IACtF,IAAI,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC,CAAC;IAClG,oEAAoE;IACpE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;CACnI;AAED,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,sDAAsD;AACtD,MAAM,WAAW,UAAU;IACzB,QAAQ,IAAI,YAAY,EAAE,CAAC;CAC5B;AAED,2EAA2E;AAC3E,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IACrD,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;CACrD;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,qCAAqC;IACrC,0BAA0B,EAAE,MAAM,CAAC;IACnC,sDAAsD;IACtD,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,kCAAkC;IAClC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,iBAAiB,CAAC;IAC7B,WAAW,EAAE,gBAAgB,CAAC;IAC9B,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAClC,KAAK,EAAE,UAAU,CAAC;IAClB,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,UAAU,CAAC;IACnB,QAAQ,EAAE,sBAAsB,CAAC;IACjC,0FAA0F;IAC1F,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC7B"}

package/dist/operator/operator-interfaces.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * Generic operator mechanism interfaces (PUBLIC-SAFE).
+ *
+ * Extracted from Kagemusha's `AgentAwarenessOptions` injection seam
+ * (~/project/mama-suite/apps/kagemusha/src/runtime/agent-awareness.ts:199-237).
+ * Kagemusha's operator is already dependency-injected; these interfaces genericize the
+ * Kagemusha-typed deps so MAMA OS can supply its own implementations.
+ *
+ * HARD RULE: no personal/business data here. Channel rosters, personas, prompts, Trello,
+ * schedule times, tokens are INJECTED via implementations/config, never in this source.
+ * See memory: project_kagemusha_port_privacy_boundary.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=operator-interfaces.js.map

package/dist/operator/operator-interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator-interfaces.js","sourceRoot":"","sources":["../../src/operator/operator-interfaces.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;GAWG"}

package/dist/operator/operator-trigger-loop.d.ts

@@ -0,0 +1,119 @@
+/**
+ * OperatorTriggerLoop - the live runtime of the trigger loop (M1-T3, extended for M2).
+ *
+ * A setInterval tick (NOT scheduler.addJob, which executes an agent prompt, not a callback;
+ * precedent: connector-ingress-manual-memory-commit.ts:742) that:
+ *   1. drains new deltas (at-least-once: commit only after processing),
+ *   2. matches active triggers -> fires them (recall memoryQuery + surface) + recordFire,
+ *   3. every authorEveryNTicks: the agent authors new triggers from the recent-events window,
+ *   4. every reviewEveryNTicks: the agent reviews fired triggers (keep/refine/retire),
+ *   5. every reportEveryNTicks: the agent composes a situational digest of the window (M2),
+ *   6. at configured LOCAL hours: the agent composes a fuller scheduled report (M2).
+ *
+ * Read-only: recall/surface/log/report-to-owner only, no write-actions (M1/M2). All deps are
+ * injected so the pipeline is unit-testable.
+ */
+import type { OperatorChannelEvent, OperatorMemoryPort, OutputSink } from './operator-interfaces.js';
+import type { TriggerRecord } from './trigger-types.js';
+import type { TriggerRegistry } from './trigger-registry.js';
+import { type AskAgent } from './trigger-author.js';
+import { type ReviewDecision } from './trigger-review.js';
+import type { ReportSchedule } from './report-scheduler.js';
+/** Structural delta source - satisfied by ConnectorDeltaRepo. */
+export interface DeltaSource {
+    drainNew(limit: number): OperatorChannelEvent[];
+    commit(events: OperatorChannelEvent[]): void;
+}
+export interface TriggerLoopConfig {
+    tickMs: number;
+    drainLimit: number;
+    authorEveryNTicks: number;
+    reviewEveryNTicks: number;
+    authorWindowSize: number;
+    /** Situational-digest cadence (M1.5 + M2 output leg). Only used when deps.output is set. */
+    reportEveryNTicks?: number;
+    /**
+     * M2.4 freshness nudge debounce (ms). A poll batch that indexes new rows wakes the loop this many
+     * ms later (Kagemusha fast-flush port). Default 15000. 0 == tick immediately on nudge.
+     */
+    nudgeDebounceMs?: number;
+}
+export interface TriggerLoopDeps {
+    delta: DeltaSource;
+    memory: OperatorMemoryPort;
+    registry: TriggerRegistry;
+    /** Agent for structured-JSON tasks: authorTriggers (real: askAgentCLI - bare CLI parses reliably). */
+    askAgent: AskAgent;
+    /**
+     * Agent for REPORT composition (M2.2). Bind this to the daemon's persona AgentLoop
+     * (SOUL.md system prompt, pinned model, session continuity) - tone/quality come from the
+     * generation inputs, and reports deserve the persona path while JSON tasks stay on the
+     * bare CLI. Absent -> reports use askAgent (explicit config choice, not a failure fallback).
+     */
+    reportAsk?: AskAgent;
+    /** Agent review of one trigger (real: reviewTriggerCLI). */
+    review: (trigger: TriggerRecord, recentContext: string[]) => Promise<ReviewDecision>;
+    /** Owner-report sink (real: telegram gateway send). Absent -> loop stays read-only. */
+    output?: Pick<OutputSink, 'send'>;
+    /** Scheduled full-report cadence (real: ReportScheduler). Absent -> full leg off (M2). */
+    reportScheduler?: ReportSchedule;
+    /**
+     * M2.3: tool-call instructions for the FULL report so the agent self-gathers context.
+     * A provider form receives the last successful report's anchor so the heavy gather
+     * can scope its delta (`since=<lastSuccessIso>`); it is resolved AT FIRE TIME.
+     */
+    fullReportSelfGather?: string[] | ((ctx: {
+        lastSuccessIso: string | null;
+    }) => string[]);
+    /**
+     * M8: board-reconcile feed. Invoked after commit with connector-qualified
+     * channelKey ("<connector>:<channelId>") and bounded delta excerpt lines
+     * (each carrying the event id so reconcile task writes can pass
+     * source_event_id). Absent -> no reconcile leg.
+     */
+    onChannelDelta?: (channelKey: string, lines: string[]) => void;
+    /** Kagemusha dual output: FULL report also publishes the operator board slots. */
+    fullReportBoardLines?: string[];
+    config: TriggerLoopConfig;
+    log: (line: string) => void;
+}
+export interface TickResult {
+    tick: number;
+    drained: number;
+    fires: number;
+    authored: number;
+    reviewed: number;
+    reported: boolean;
+    fullReported: boolean;
+}
+export declare class OperatorTriggerLoop {
+    private deps;
+    private tickCount;
+    private recentEvents;
+    private running;
+    private nudgeTimer;
+    private digest;
+    private fullReporter;
+    constructor(deps: TriggerLoopDeps);
+    tick(): Promise<TickResult>;
+    /**
+     * M2.4 freshness nudge: wake the loop to tick ~nudgeDebounceMs from now instead of waiting for the
+     * next scheduled interval. The connector sink calls this (via a forwarder) whenever a poll batch
+     * indexes new rows.
+     *
+     * Debounced (Kagemusha fast-flush port, agent-awareness.ts:322-332 mechanism): the FIRST nudge in
+     * a quiet window arms one timer; further nudges while it is armed are ignored, so a burst of poll
+     * batches collapses to a single extra tick. Busy-safe (agent-awareness.ts:343-346 mechanism): if a
+     * tick is in flight when the timer fires, the nudge is skipped - never concurrent ticks; the
+     * uncommitted deltas simply wait for the next tick. Pure timing assist: it only changes WHEN an
+     * existing tick runs, never WHAT it does.
+     */
+    nudge(): void;
+    /**
+     * Start ticking on the configured interval. Returns a stop function.
+     * The interval wrapper catches + logs tick errors so one bad tick does not kill the loop
+     * (the error is still surfaced loudly in the log - not swallowed).
+     */
+    start(): () => void;
+}
+//# sourceMappingURL=operator-trigger-loop.d.ts.map

package/dist/operator/operator-trigger-loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator-trigger-loop.d.ts","sourceRoot":"","sources":["../../src/operator/operator-trigger-loop.ts"],"names":[],"mappings":"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"}

package/dist/operator/operator-trigger-loop.js

@@ -0,0 +1,267 @@
+"use strict";
+/**
+ * OperatorTriggerLoop - the live runtime of the trigger loop (M1-T3, extended for M2).
+ *
+ * A setInterval tick (NOT scheduler.addJob, which executes an agent prompt, not a callback;
+ * precedent: connector-ingress-manual-memory-commit.ts:742) that:
+ *   1. drains new deltas (at-least-once: commit only after processing),
+ *   2. matches active triggers -> fires them (recall memoryQuery + surface) + recordFire,
+ *   3. every authorEveryNTicks: the agent authors new triggers from the recent-events window,
+ *   4. every reviewEveryNTicks: the agent reviews fired triggers (keep/refine/retire),
+ *   5. every reportEveryNTicks: the agent composes a situational digest of the window (M2),
+ *   6. at configured LOCAL hours: the agent composes a fuller scheduled report (M2).
+ *
+ * Read-only: recall/surface/log/report-to-owner only, no write-actions (M1/M2). All deps are
+ * injected so the pipeline is unit-testable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OperatorTriggerLoop = void 0;
+const trigger_matcher_js_1 = require("./trigger-matcher.js");
+const trigger_fire_js_1 = require("./trigger-fire.js");
+const trigger_author_js_1 = require("./trigger-author.js");
+const trigger_review_js_1 = require("./trigger-review.js");
+const situation_report_js_1 = require("./situation-report.js");
+class OperatorTriggerLoop {
+    deps;
+    tickCount = 0;
+    recentEvents = [];
+    running = false;
+    nudgeTimer = null;
+    digest;
+    fullReporter;
+    constructor(deps) {
+        this.deps = deps;
+        // G2 success signal: when a sent report cites fired triggers (USED_TRIGGERS
+        // trailer, window-validated), record 'succeeded' on each. Uncited fires stay
+        // neutral; elimination still comes from the review pass. Detector-based fires
+        // carry the detector name as id and are not in the registry -- skip loudly.
+        const recordTriggerUse = (ids) => {
+            for (const id of ids) {
+                try {
+                    deps.registry.recordOutcome(id, 'succeeded');
+                    deps.log(`[trigger-loop] outcome succeeded trigger=${id} (cited in owner report)`);
+                }
+                catch (err) {
+                    deps.log(`[trigger-loop] outcome skip trigger=${id}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        };
+        this.digest = new situation_report_js_1.SituationReporter({ recordTriggerUse });
+        this.fullReporter = new situation_report_js_1.SituationReporter({
+            // Wrap a provider into a zero-arg closure resolved AT FIRE TIME (buildPrompt
+            // calls it): the delta anchor is the last SUCCESSFUL full report, so a run
+            // that failed never widens the next window (defer, never drop).
+            selfGatherLines: typeof deps.fullReportSelfGather === 'function'
+                ? () => deps.fullReportSelfGather({
+                    lastSuccessIso: deps.reportScheduler?.loadLastSuccess() ?? null,
+                })
+                : (deps.fullReportSelfGather ?? []),
+            boardPublishLines: deps.fullReportBoardLines,
+            recordTriggerUse,
+        });
+    }
+    async tick() {
+        const { delta, memory, registry, askAgent, review, config, log } = this.deps;
+        const { output, reportScheduler } = this.deps;
+        const fullLegOn = Boolean(output && reportScheduler);
+        this.tickCount += 1;
+        const tick = this.tickCount;
+        // 1. Drain new deltas (commit AFTER processing - at-least-once).
+        const events = delta.drainNew(config.drainLimit);
+        if (events.length > 0) {
+            log(`[trigger-loop] tick ${tick}: drained ${events.length} events`);
+        }
+        // 2. Match + fire + recordFire, folding fire activity into the report accumulators.
+        let fires = 0;
+        for (const event of events) {
+            const signals = (0, trigger_matcher_js_1.matchTriggers)(event, registry);
+            for (const signal of signals) {
+                const result = await (0, trigger_fire_js_1.fireTrigger)(signal, memory);
+                fires += 1;
+                if (signal.triggerId) {
+                    registry.recordFire(signal.triggerId);
+                }
+                // Carry the recalled {topic, content} (agent-authored memoryQuery drove it) into the report.
+                this.digest.recordFire({
+                    triggerId: signal.triggerId ?? signal.detector,
+                    kind: signal.kind,
+                    channelId: signal.channelId,
+                    recalled: result.recalled,
+                });
+                if (fullLegOn) {
+                    this.fullReporter.recordFire({
+                        triggerId: signal.triggerId ?? signal.detector,
+                        kind: signal.kind,
+                        channelId: signal.channelId,
+                        recalled: result.recalled,
+                    });
+                }
+                log(`[trigger-loop] tick ${tick}: fire trigger=${signal.triggerId ?? signal.detector} ` +
+                    `recalled=${result.recalled.length} channel=${signal.channelId}`);
+            }
+        }
+        delta.commit(events);
+        // M8: feed the board-reconcile leg AFTER commit (the loop's cursor is
+        // authoritative; reconcile is a freshness layer repaired by the 30-min cron).
+        if (this.deps.onChannelDelta && events.length > 0) {
+            const byChannel = new Map();
+            for (const event of events) {
+                const key = `${event.channel}:${event.channelId}`;
+                const bucket = byChannel.get(key) ?? [];
+                bucket.push(event);
+                byChannel.set(key, bucket);
+            }
+            for (const [channelKey, channelEvents] of byChannel) {
+                const lines = channelEvents
+                    .slice(-10)
+                    .map((e) => `- [id:${e.eventIndexId ?? e.id}] ${e.userId}: ${e.content.trim().slice(0, 200)}`);
+                try {
+                    this.deps.onChannelDelta(channelKey, lines);
+                }
+                catch (err) {
+                    log(`[trigger-loop] onChannelDelta failed for ${channelKey}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        }
+        // Feed the drained window into the report accumulators (bounded per-channel) and keep the
+        // author window. The digest reports on ALL channels seen, not only the ones that fired.
+        if (events.length > 0) {
+            this.digest.recordWindow(events);
+            if (fullLegOn) {
+                this.fullReporter.recordWindow(events);
+            }
+            this.recentEvents = [...this.recentEvents, ...events].slice(-config.authorWindowSize);
+        }
+        // 3. Agent authors new triggers from the recent window.
+        let authored = 0;
+        if (tick % config.authorEveryNTicks === 0 && this.recentEvents.length > 0) {
+            const created = await (0, trigger_author_js_1.authorTriggers)(this.recentEvents, registry, askAgent, {
+                note: `authored at tick ${tick}`,
+            });
+            authored = created.length;
+            if (authored > 0) {
+                this.digest.recordAuthored(authored);
+                if (fullLegOn) {
+                    this.fullReporter.recordAuthored(authored);
+                }
+            }
+            log(`[trigger-loop] tick ${tick}: author pass created ${authored} trigger(s)`);
+        }
+        // 4. Agent reviews triggers that have actually fired.
+        let reviewed = 0;
+        if (tick % config.reviewEveryNTicks === 0) {
+            const firedTriggers = registry.listActive().filter((t) => t.stats.fired > 0);
+            const context = this.recentEvents.map((e) => `[${e.channelId}] ${e.content}`);
+            for (const trigger of firedTriggers) {
+                const decision = await review(trigger, context);
+                const action = (0, trigger_review_js_1.applyReview)(decision, trigger.id, registry);
+                reviewed += 1;
+                log(`[trigger-loop] tick ${tick}: review trigger=${trigger.id} -> ${action}`);
+            }
+        }
+        // 5. Situational digest (M1.5 cadence, M2 window-aware): the agent composes it from the
+        //    window + fire activity + recalled memory; the sink delivers it. Agent may reply NOTHING.
+        let reported = false;
+        const reportAsk = this.deps.reportAsk ?? askAgent;
+        const reportEvery = config.reportEveryNTicks ?? 0;
+        if (output && reportEvery > 0 && tick % reportEvery === 0 && this.digest.hasActivity()) {
+            reported = await this.digest.report(reportAsk, output, 'digest');
+            log(`[trigger-loop] tick ${tick}: owner digest ${reported ? 'SENT' : 'suppressed by agent'}`);
+        }
+        // 6. Scheduled full report (M2): fires at configured LOCAL hours - even on a completely
+        //    quiet window (M2.1 aliveness: the agent reports "quiet" instead of skipping; owners
+        //    rely on the scheduled report arriving). Fires once per hour (markFired persists the
+        //    hour key -> restart-safe). Send failure throws (no-fallback) WITHOUT marking the hour,
+        //    so the next tick retries with the buffer intact.
+        let fullReported = false;
+        if (output && reportScheduler) {
+            const { fire, hourKey } = reportScheduler.shouldFire(new Date());
+            if (fire) {
+                // Anchor = FIRE time, captured BEFORE the run: anchoring at completion would
+                // leave a gap (messages arriving while the run executes fall after the gather
+                // but before a completion-time anchor). Overlap is tolerable; gaps are not.
+                const firedAtIso = new Date().toISOString();
+                fullReported = await this.fullReporter.report(reportAsk, output, 'full');
+                reportScheduler.markFired(hourKey); // reached only if report() did not throw (sent OR agent-suppressed)
+                if (fullReported) {
+                    // ONLY a delivered report advances the delta anchor. A NOTHING-suppressed
+                    // report or a Task-4 ENVELOPE_EXPIRED abort must NOT advance it, so the
+                    // next report's window still covers everything this run missed.
+                    reportScheduler.markSuccess(firedAtIso);
+                }
+                log(`[trigger-loop] tick ${tick}: full report ${fullReported ? 'SENT' : 'suppressed by agent'} (${hourKey})`);
+            }
+        }
+        return { tick, drained: events.length, fires, authored, reviewed, reported, fullReported };
+    }
+    /**
+     * M2.4 freshness nudge: wake the loop to tick ~nudgeDebounceMs from now instead of waiting for the
+     * next scheduled interval. The connector sink calls this (via a forwarder) whenever a poll batch
+     * indexes new rows.
+     *
+     * Debounced (Kagemusha fast-flush port, agent-awareness.ts:322-332 mechanism): the FIRST nudge in
+     * a quiet window arms one timer; further nudges while it is armed are ignored, so a burst of poll
+     * batches collapses to a single extra tick. Busy-safe (agent-awareness.ts:343-346 mechanism): if a
+     * tick is in flight when the timer fires, the nudge is skipped - never concurrent ticks; the
+     * uncommitted deltas simply wait for the next tick. Pure timing assist: it only changes WHEN an
+     * existing tick runs, never WHAT it does.
+     */
+    nudge() {
+        if (this.nudgeTimer)
+            return; // already armed - debounce collapses the burst
+        const configured = this.deps.config.nudgeDebounceMs;
+        const debounceMs = typeof configured === 'number' && Number.isFinite(configured) && configured >= 0
+            ? configured
+            : 15_000;
+        this.nudgeTimer = setTimeout(() => {
+            this.nudgeTimer = null;
+            if (this.running) {
+                this.deps.log('[trigger-loop] nudge: tick already running - skipped (deltas wait for next tick)');
+                return;
+            }
+            this.running = true;
+            void this.tick()
+                .catch((error) => {
+                this.deps.log(`[trigger-loop] nudge tick failed: ${error instanceof Error ? error.message : String(error)}`);
+            })
+                .finally(() => {
+                this.running = false;
+            });
+        }, debounceMs);
+        this.nudgeTimer.unref?.();
+    }
+    /**
+     * Start ticking on the configured interval. Returns a stop function.
+     * The interval wrapper catches + logs tick errors so one bad tick does not kill the loop
+     * (the error is still surfaced loudly in the log - not swallowed).
+     */
+    start() {
+        const { config, log } = this.deps;
+        const handle = setInterval(() => {
+            if (this.running) {
+                log('[trigger-loop] tick skipped: previous tick still running');
+                return;
+            }
+            this.running = true;
+            void this.tick()
+                .catch((error) => {
+                log(`[trigger-loop] tick failed: ${error instanceof Error ? error.message : String(error)}`);
+            })
+                .finally(() => {
+                this.running = false;
+            });
+        }, config.tickMs);
+        handle.unref?.();
+        log(`[trigger-loop] started (tick every ${config.tickMs}ms)`);
+        return () => {
+            clearInterval(handle);
+            if (this.nudgeTimer) {
+                clearTimeout(this.nudgeTimer);
+                this.nudgeTimer = null;
+            }
+            log('[trigger-loop] stopped');
+        };
+    }
+}
+exports.OperatorTriggerLoop = OperatorTriggerLoop;
+//# sourceMappingURL=operator-trigger-loop.js.map

package/dist/operator/operator-trigger-loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operator-trigger-loop.js","sourceRoot":"","sources":["../../src/operator/operator-trigger-loop.ts"],"names":[],"mappings":"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"}

package/dist/operator/report-run.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Operator report-run wiring + tool-use audit (M3 "Operator Hands").
+ *
+ * PURE half (this file, Task 1): classify the gateway tools the persona agent actually EXECUTED
+ * during a report. Gateway calls are prompt-based ```tool_call blocks, parsed by AgentLoop into
+ * tool_use blocks (agent-loop.ts:1218-1226,1330-1333); each execution's tool_result is pushed
+ * into the NEXT user message (agent-loop.ts:1408-1411). We pair tool_use.id with its tool_result
+ * and count executions only - errored results and envelope denials ("success":false /
+ * envelope_missing, gateway-tool-executor.ts:1090-1142) do NOT count. History is read
+ * structurally (no agent-internal imports) so the audit is trivially unit-testable.
+ *
+ * The audit powers two M3 guarantees:
+ *   - no-fallback (GAP 1): a FULL report that EXECUTED no gateway gather tool (none emitted, or
+ *     every call denied/errored) is WARNED loudly, never silently accepted as if it had
+ *     task-board substance.
+ *   - observability (GAP 2): every write (mama_save) is logged loudly.
+ *
+ * ASCII-only. No personal strings.
+ */
+import type { AskAgent } from './trigger-author.js';
+/** Dedicated persona session lane for operator reports; isolates the multi-turn gather loop from
+ *  chat. runWithContent honors options.sessionKey (agent-loop.ts:879). */
+export declare const OPERATOR_REPORT_SESSION_KEY = "operator:report";
+/** Minimal structural view of AgentLoopResult.history (types.ts:1105). Structural on purpose:
+ *  keeps this module free of agent-internal imports so tests use plain synthetic objects. */
+export interface ReportHistoryMessage {
+    role: string;
+    content: unknown;
+}
+export interface ReportToolAudit {
+    gatherTools: string[];
+    writeTools: string[];
+    all: string[];
+}
+/** Pair assistant tool_use blocks with their tool_result and classify EXECUTIONS as gather vs
+ *  write. `all` inventories every emission (executed or not) for honest logging. */
+export declare function summarizeReportToolUse(history: ReadonlyArray<ReportHistoryMessage>): ReportToolAudit;
+/**
+ * Build the operator-log lines for one report.
+ * isFullReport gates the no-fallback gather WARNING (only the FULL report is instructed to gather;
+ * the digest is intentionally tool-free, so absence of gather tools there is normal).
+ */
+export declare function formatReportToolAudit(audit: ReportToolAudit, isFullReport: boolean): string[];
+export interface PersonaReportRunResult {
+    response: string;
+    history: ReadonlyArray<ReportHistoryMessage>;
+}
+/** E = the envelope type; generic keeps this module free of agent/envelope imports while start.ts
+ *  gets full inference (no casts): E is inferred from the injected issuer's return type. */
+export interface PersonaReportRunner<E = unknown> {
+    (prompt: string, envelope?: E): Promise<PersonaReportRunResult>;
+}
+export interface PersonaReportAskDeps<E = unknown> {
+    run: PersonaReportRunner<E>;
+    log: (line: string) => void;
+    /** Marker that identifies a FULL report prompt (situation-report.OPERATOR_FULL_REPORT_TAG). */
+    fullReportTag: string;
+    /**
+     * Issue a per-report scoped worker envelope. Gateway 'model_tool' executions are envelope-gated
+     * (gateway-tool-executor.ts:252-256): without an envelope every call is denied with code
+     * 'envelope_missing' (:1090-1142). Injected from start.ts (envelopeAuthority.buildAndPersist);
+     * omit ONLY when issuance mode is 'off'. Failures propagate (no-fallback).
+     */
+    issueEnvelope?: () => Promise<E>;
+}
+/**
+ * Build the report-composition AskAgent (M3). Envelope-first: gateway 'model_tool' executions are
+ * envelope-gated (gateway-tool-executor.ts:252-256), so issue the per-report scoped envelope
+ * BEFORE running - without one every call is denied with code 'envelope_missing' (:1090-1142),
+ * the enforcement that killed the ancestor scheduled-report path. Issuance failure propagates
+ * loudly (no-fallback; the buffer is kept and the next cadence retries). Then run the persona
+ * agent (injected runner isolates the report into its own session lane and carries the envelope),
+ * audit + log the gateway tools it actually EXECUTED (no-fallback WARNING when a full report
+ * executed none; observability line for every write), and enforce the empty-report guard
+ * (M2 semantics).
+ */
+export declare function createPersonaReportAsk<E = unknown>(deps: PersonaReportAskDeps<E>): AskAgent;
+//# sourceMappingURL=report-run.d.ts.map

package/dist/operator/report-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-run.d.ts","sourceRoot":"","sources":["../../src/operator/report-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD;0EAC0E;AAC1E,eAAO,MAAM,2BAA2B,oBAAoB,CAAC;AAwB7D;6FAC6F;AAC7F,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,GAAG,EAAE,MAAM,EAAE,CAAC;CACf;AA2BD;oFACoF;AACpF,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,aAAa,CAAC,oBAAoB,CAAC,GAC3C,eAAe,CAgCjB;AAMD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,eAAe,EAAE,YAAY,EAAE,OAAO,GAAG,MAAM,EAAE,CAmB7F;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAAC;CAC9C;AACD;4FAC4F;AAC5F,MAAM,WAAW,mBAAmB,CAAC,CAAC,GAAG,OAAO;IAC9C,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACjE;AACD,MAAM,WAAW,oBAAoB,CAAC,CAAC,GAAG,OAAO;IAC/C,GAAG,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC;IAC5B,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,+FAA+F;IAC/F,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,CAAC;CAClC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAAG,QAAQ,CAa3F"}