@jungjaehoon/mama-os 0.20.1 → 0.22.0

package/dist/operator/report-run.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OPERATOR_REPORT_SESSION_KEY = void 0;
+exports.summarizeReportToolUse = summarizeReportToolUse;
+exports.formatReportToolAudit = formatReportToolAudit;
+exports.createPersonaReportAsk = createPersonaReportAsk;
+/** Dedicated persona session lane for operator reports; isolates the multi-turn gather loop from
+ *  chat. runWithContent honors options.sessionKey (agent-loop.ts:879). */
+exports.OPERATOR_REPORT_SESSION_KEY = 'operator:report';
+/** Gateway READ tools the full report is instructed to gather with (gateway-tools.md:12,14,22-25). */
+const GATHER_TOOLS = new Set([
+    'kagemusha_overview',
+    'kagemusha_entities',
+    'kagemusha_tasks',
+    'kagemusha_messages',
+    'mama_recall',
+    'mama_search',
+    'context_compile',
+]);
+/** Gateway WRITE tools. mama_save is the M3 hand; the rest are classified only for honest
+ *  observability if they ever appear (report_publish/wiki_publish are NOT instructed in M3 -
+ *  see plan finding F6). (gateway-tools.md:11,17,18,65,66) */
+const WRITE_TOOLS = new Set([
+    'mama_save',
+    'mama_add',
+    'mama_ingest',
+    'report_publish',
+    'wiki_publish',
+]);
+/** True when a tool_result proves the call did NOT execute: errored, or denied by the envelope
+ *  layer with {"success":false,...,"code":"envelope_missing"} (gateway-tool-executor.ts:1090-1142).
+ *  The gateway loop serializes the tool-result OBJECT as the content (JSON.stringify in
+ *  executeTools), so parse and inspect the ROOT properties first - a substring regex alone
+ *  false-positives on a SUCCESSFUL result whose nested payload merely mentions
+ *  '"success":false' (PR #119 review). The substring heuristic remains only as the
+ *  conservative fallback for unparseable content. */
+function isErroredOrDenied(block) {
+    if (block.is_error === true) {
+        return true;
+    }
+    const body = typeof block.content === 'string' ? block.content : JSON.stringify(block.content ?? '');
+    try {
+        const parsed = JSON.parse(body);
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+            const root = parsed;
+            return root.success === false || root.code === 'envelope_missing';
+        }
+    }
+    catch {
+        // Not JSON - fall through to the conservative substring heuristic.
+    }
+    return /"success"\s*:\s*false/.test(body) || body.includes('envelope_missing');
+}
+/** 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. */
+function summarizeReportToolUse(history) {
+    // Pass 1: index result health by tool_use_id (results live in the user messages the agent loop
+    // pushes after each tool batch - agent-loop.ts:1408-1411).
+    const resultOkById = new Map();
+    for (const msg of history) {
+        if (!msg || msg.role !== 'user' || !Array.isArray(msg.content))
+            continue;
+        for (const block of msg.content) {
+            if (!block || block.type !== 'tool_result' || typeof block.tool_use_id !== 'string')
+                continue;
+            resultOkById.set(block.tool_use_id, !isErroredOrDenied(block));
+        }
+    }
+    // Pass 2: classify assistant tool_use blocks; only a paired healthy result counts as executed.
+    const gatherTools = [];
+    const writeTools = [];
+    const all = [];
+    for (const msg of history) {
+        if (!msg || msg.role !== 'assistant' || !Array.isArray(msg.content))
+            continue;
+        for (const block of msg.content) {
+            if (!block || block.type !== 'tool_use' || typeof block.name !== 'string')
+                continue;
+            all.push(block.name);
+            const executed = typeof block.id === 'string' && resultOkById.get(block.id) === true;
+            if (!executed)
+                continue;
+            if (GATHER_TOOLS.has(block.name))
+                gatherTools.push(block.name);
+            else if (WRITE_TOOLS.has(block.name))
+                writeTools.push(block.name);
+        }
+    }
+    return { gatherTools, writeTools, all };
+}
+function uniq(names) {
+    return [...new Set(names)];
+}
+/**
+ * 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).
+ */
+function formatReportToolAudit(audit, isFullReport) {
+    const lines = [];
+    if (audit.writeTools.length > 0) {
+        lines.push(`[trigger-loop] full report: agent wrote via ${uniq(audit.writeTools).join(', ')}`);
+    }
+    if (isFullReport) {
+        if (audit.gatherTools.length === 0) {
+            lines.push('[trigger-loop] full report WARNING: agent executed NO gateway gather tools ' +
+                '(none called, or every call errored/denied) - task-board substance NOT verified; ' +
+                'the report may reflect native-tool, denied, or window-only gathering');
+        }
+        else {
+            lines.push(`[trigger-loop] full report: agent gathered via ${uniq(audit.gatherTools).join(', ')}`);
+        }
+    }
+    return lines;
+}
+/**
+ * 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).
+ */
+function createPersonaReportAsk(deps) {
+    return async (prompt) => {
+        const envelope = deps.issueEnvelope ? await deps.issueEnvelope() : undefined;
+        const { response, history } = await deps.run(prompt, envelope);
+        const isFull = prompt.includes(deps.fullReportTag);
+        for (const line of formatReportToolAudit(summarizeReportToolUse(history), isFull)) {
+            deps.log(line);
+        }
+        if (!response || response.trim() === '') {
+            throw new Error('persona agent returned an empty report response');
+        }
+        return response;
+    };
+}
+//# sourceMappingURL=report-run.js.map

package/dist/operator/report-run.js.map

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

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

@@ -0,0 +1,66 @@
+/** Injectable schedule seam - the loop depends on this, not the concrete class (DI + testability). */
+export interface ReportSchedule {
+    shouldFire(now: Date): {
+        fire: boolean;
+        hourKey: string;
+    };
+    markFired(hourKey: string): void;
+    /** Anchor timestamp (ISO) of the last SUCCESSFUL full report, for delta-scoped gathers. */
+    loadLastSuccess(): string | null;
+    /** Persist the anchor after a full report is delivered (failures must never advance it). */
+    markSuccess(iso: string): void;
+}
+/** Persist/restore the last-fired hour key (so a restart within the same hour does not re-send). */
+export interface ReportScheduleStore {
+    load(): string | null;
+    save(hourKey: string): void;
+    /** Anchor timestamp (ISO) of the last SUCCESSFUL full report; null before the first one. */
+    loadLastSuccess(): string | null;
+    /** Persist the success anchor (read-modify-write so it never clobbers the fired-hour key). */
+    markSuccess(iso: string): void;
+}
+/** Local-time "YYYY-MM-DD:HH" bucket. Two ticks in the same local hour share a key. */
+export declare function hourKeyLocal(now: Date): string;
+/**
+ * Parse an env string like "8,13,18" into sorted, deduped LOCAL hours in [0,23].
+ * Empty/garbage -> [] (feature off). Ports Kagemusha normalizeFullReportHours
+ * (~/project/mama-suite/apps/kagemusha/src/config/ai-config.ts:203) but generic + ASCII, no
+ * personal defaults.
+ */
+export declare function parseReportHours(raw: string): number[];
+export declare class ReportScheduler implements ReportSchedule {
+    private hours;
+    private store;
+    private lastFiredHourKey;
+    constructor(hours: number[], store: ReportScheduleStore);
+    /** Pure: does a full report fire at now? Robust to ticks not landing on the hour boundary. */
+    shouldFire(now: Date): {
+        fire: boolean;
+        hourKey: string;
+    };
+    /** Mark this hour delivered (persist) so we fire once per configured hour, restart-safe. */
+    markFired(hourKey: string): void;
+    /** Anchor of the last SUCCESSFUL full report (delegates to the store). */
+    loadLastSuccess(): string | null;
+    /** Persist the success anchor (delegates to the store; called ONLY on a delivered report). */
+    markSuccess(iso: string): void;
+}
+/** File-backed store under ~/.mama - mirrors ConnectorDeltaRepo's atomic cursor file. */
+export declare class FileReportScheduleStore implements ReportScheduleStore {
+    private path;
+    constructor(path: string);
+    /**
+     * Read-parse the whole state object. MISSING file -> {} (silent, as today). A corrupt/empty
+     * or non-object state file is disposable bookkeeping: rather than throw and permanently break
+     * the report leg, reset LOUDLY and return {}. Worst case after a reset is one duplicate report
+     * plus a wide gather window - both self-heal on the next successful report.
+     */
+    private readState;
+    /** Atomic full-object write (tmp+rename) - callers do read-modify-write to preserve sibling fields. */
+    private writeState;
+    load(): string | null;
+    save(hourKey: string): void;
+    loadLastSuccess(): string | null;
+    markSuccess(iso: string): void;
+}
+//# sourceMappingURL=report-scheduler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"report-scheduler.d.ts","sourceRoot":"","sources":["../../src/operator/report-scheduler.ts"],"names":[],"mappings":"AAeA,sGAAsG;AACtG,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,GAAG,EAAE,IAAI,GAAG;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1D,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,2FAA2F;IAC3F,eAAe,IAAI,MAAM,GAAG,IAAI,CAAC;IACjC,4FAA4F;IAC5F,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,oGAAoG;AACpG,MAAM,WAAW,mBAAmB;IAClC,IAAI,IAAI,MAAM,GAAG,IAAI,CAAC;IACtB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,4FAA4F;IAC5F,eAAe,IAAI,MAAM,GAAG,IAAI,CAAC;IACjC,8FAA8F;IAC9F,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,uFAAuF;AACvF,wBAAgB,YAAY,CAAC,GAAG,EAAE,IAAI,GAAG,MAAM,CAG9C;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAQtD;AAED,qBAAa,eAAgB,YAAW,cAAc;IACpD,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,gBAAgB,CAAgB;gBAE5B,KAAK,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,mBAAmB;IAMvD,8FAA8F;IAC9F,UAAU,CAAC,GAAG,EAAE,IAAI,GAAG;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE;IAMzD,4FAA4F;IAC5F,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAKhC,0EAA0E;IAC1E,eAAe,IAAI,MAAM,GAAG,IAAI;IAIhC,8FAA8F;IAC9F,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAG/B;AAED,yFAAyF;AACzF,qBAAa,uBAAwB,YAAW,mBAAmB;IACjE,OAAO,CAAC,IAAI,CAAS;gBAET,IAAI,EAAE,MAAM;IAIxB;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAwBjB,uGAAuG;IACvG,OAAO,CAAC,UAAU;IAOlB,IAAI,IAAI,MAAM,GAAG,IAAI;IAKrB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAS3B,eAAe,IAAI,MAAM,GAAG,IAAI;IAKhC,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;CAU/B"}

package/dist/operator/report-scheduler.js

@@ -0,0 +1,135 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileReportScheduleStore = exports.ReportScheduler = void 0;
+exports.hourKeyLocal = hourKeyLocal;
+exports.parseReportHours = parseReportHours;
+/**
+ * ReportScheduler - the scheduled full-report cadence (M2-T0).
+ *
+ * Ports the schedule-firing MECHANISM from Kagemusha AgentAwareness.tickScheduledReports
+ * (~/project/mama-suite/apps/kagemusha/src/runtime/agent-awareness.ts:1371 + buildHourKey:1483):
+ * fire once when the current hour is one of the configured hours and this hour has not been fired
+ * yet. Kagemusha keys on Asia/Seoul; MAMA uses LOCAL hours (Date.getHours) per the M2 brief - the
+ * owner timezone stays a runtime property, never a source constant.
+ *
+ * Pure decision (shouldFire) + a persisted last-fired hour key (survives restart -> no
+ * double-send). NO personal data: the hours are injected from env/config, never hardcoded here.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/** Local-time "YYYY-MM-DD:HH" bucket. Two ticks in the same local hour share a key. */
+function hourKeyLocal(now) {
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}:${pad(now.getHours())}`;
+}
+/**
+ * Parse an env string like "8,13,18" into sorted, deduped LOCAL hours in [0,23].
+ * Empty/garbage -> [] (feature off). Ports Kagemusha normalizeFullReportHours
+ * (~/project/mama-suite/apps/kagemusha/src/config/ai-config.ts:203) but generic + ASCII, no
+ * personal defaults.
+ */
+function parseReportHours(raw) {
+    const hours = raw
+        .split(',')
+        .map((part) => part.trim())
+        .filter((part) => part !== '') // drop empty tokens BEFORE Number(): Number('') === 0 would sneak in hour 0
+        .map(Number)
+        .filter((n) => Number.isInteger(n) && n >= 0 && n <= 23);
+    return [...new Set(hours)].sort((a, b) => a - b);
+}
+class ReportScheduler {
+    hours;
+    store;
+    lastFiredHourKey;
+    constructor(hours, store) {
+        this.hours = hours;
+        this.store = store;
+        this.lastFiredHourKey = store.load(); // restore across restart
+    }
+    /** Pure: does a full report fire at now? Robust to ticks not landing on the hour boundary. */
+    shouldFire(now) {
+        const hourKey = hourKeyLocal(now);
+        const fire = this.hours.includes(now.getHours()) && this.lastFiredHourKey !== hourKey;
+        return { fire, hourKey };
+    }
+    /** Mark this hour delivered (persist) so we fire once per configured hour, restart-safe. */
+    markFired(hourKey) {
+        this.lastFiredHourKey = hourKey;
+        this.store.save(hourKey);
+    }
+    /** Anchor of the last SUCCESSFUL full report (delegates to the store). */
+    loadLastSuccess() {
+        return this.store.loadLastSuccess();
+    }
+    /** Persist the success anchor (delegates to the store; called ONLY on a delivered report). */
+    markSuccess(iso) {
+        this.store.markSuccess(iso);
+    }
+}
+exports.ReportScheduler = ReportScheduler;
+/** File-backed store under ~/.mama - mirrors ConnectorDeltaRepo's atomic cursor file. */
+class FileReportScheduleStore {
+    path;
+    constructor(path) {
+        this.path = path;
+    }
+    /**
+     * Read-parse the whole state object. MISSING file -> {} (silent, as today). A corrupt/empty
+     * or non-object state file is disposable bookkeeping: rather than throw and permanently break
+     * the report leg, reset LOUDLY and return {}. Worst case after a reset is one duplicate report
+     * plus a wide gather window - both self-heal on the next successful report.
+     */
+    readState() {
+        if (!(0, node_fs_1.existsSync)(this.path)) {
+            return {};
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse((0, node_fs_1.readFileSync)(this.path, 'utf8'));
+        }
+        catch (error) {
+            console.error('[report-scheduler] state file corrupt or unreadable - resetting schedule state:', error);
+            return {};
+        }
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+            console.error('[report-scheduler] state file corrupt or unreadable - resetting schedule state:', `not a plain object: ${this.path}`);
+            return {};
+        }
+        return parsed;
+    }
+    /** Atomic full-object write (tmp+rename) - callers do read-modify-write to preserve sibling fields. */
+    writeState(state) {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(this.path), { recursive: true });
+        const tmp = (0, node_path_1.join)((0, node_path_1.dirname)(this.path), `.report-schedule.${process.pid}.tmp`);
+        (0, node_fs_1.writeFileSync)(tmp, JSON.stringify(state), 'utf8');
+        (0, node_fs_1.renameSync)(tmp, this.path); // atomic replace
+    }
+    load() {
+        const key = this.readState().lastFiredHourKey;
+        return typeof key === 'string' ? key : null;
+    }
+    save(hourKey) {
+        // Read-modify-write: markFired must NOT clobber the success anchor.
+        const state = this.readState();
+        this.writeState({
+            lastFiredHourKey: hourKey,
+            ...(typeof state.lastSuccessIso === 'string' ? { lastSuccessIso: state.lastSuccessIso } : {}),
+        });
+    }
+    loadLastSuccess() {
+        const iso = this.readState().lastSuccessIso;
+        return typeof iso === 'string' ? iso : null;
+    }
+    markSuccess(iso) {
+        // Read-modify-write: advancing the anchor must NOT clobber the fired-hour key.
+        const state = this.readState();
+        this.writeState({
+            ...(typeof state.lastFiredHourKey === 'string'
+                ? { lastFiredHourKey: state.lastFiredHourKey }
+                : {}),
+            lastSuccessIso: iso,
+        });
+    }
+}
+exports.FileReportScheduleStore = FileReportScheduleStore;
+//# sourceMappingURL=report-scheduler.js.map

package/dist/operator/report-scheduler.js.map

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

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

@@ -0,0 +1,90 @@
+/**
+ * SituationReporter - the OUTPUT leg of the trigger loop (M2), superseding TriggerReporter (M1.5).
+ *
+ * Accumulates a BOUNDED window of drained events (per-channel counts + last-K excerpts), plus
+ * fire/author activity and the memory those fires recalled (agent-authored memoryQuery drove the
+ * recall - trigger-fire.ts:33-34). On a report cadence the AGENT composes an owner situation
+ * report from the AGGREGATE (agent-first: the agent judges content and may reply NOTHING to
+ * suppress); the system only windows/schedules/sends.
+ *
+ * Two framings share one accumulator + send machinery:
+ *   - 'digest': the short periodic update (the M1.5 fire digest, now window-aware).
+ *   - 'full'  : the fuller scheduled report covering the whole window since the last full report.
+ *
+ * No activity -> no agent call, no send (no spam). Send failure propagates loudly (no-fallback)
+ * and keeps the buffer so the next cadence retries. English default; the agent is told to answer
+ * in the owner's language if inferable. NO personal strings in this source.
+ */
+import type { OperatorChannelEvent, OutputSink } from './operator-interfaces.js';
+import type { AskAgent } from './trigger-author.js';
+/**
+ * Machine frame tag prepended to the FULL report prompt so the report-run wiring can tell a full
+ * report from a digest for tool-use auditing (report-run.ts). Kagemusha frames its scheduled full
+ * report with the same bracketed-tag convention (report-prompts.ts buildFullReportPrompt).
+ */
+export declare const OPERATOR_FULL_REPORT_TAG = "[operator_full_report]";
+export interface FireActivity {
+    triggerId: string;
+    kind: string;
+    channelId: string;
+    recalled: {
+        topic: string;
+        content: string;
+    }[];
+}
+export type ReportMode = 'digest' | 'full';
+export interface SituationReporterOptions {
+    /**
+     * M2.3: tool-call instructions injected into the FULL report framing so the agent
+     * ACTIVELY gathers current context (channels, tasks, memory) before writing - the
+     * lesson from Kagemusha, whose report prompt instructs its agent to call its tools
+     * (and which deleted its deterministic report builder for low quality). The lines
+     * are injected from the runtime wiring (which knows the daemon's toolset); this
+     * module stays generic. Digest mode never uses them (frequent + must stay light).
+     *
+     * A zero-arg provider is resolved at fire time (buildPrompt runs per report),
+     * so runtime wiring can inject freshly anchored gather lines (e.g. a delta
+     * `since=<last successful report>`) without rebuilding the reporter.
+     */
+    selfGatherLines?: string[] | (() => string[]);
+    /**
+     * Kagemusha dual-output mechanism: lines instructing the FULL report run to also
+     * publish the operator board slots (report_publish) before writing the text
+     * report. Injected from runtime wiring (board-slot-instructions.ts); digest mode
+     * never publishes the board.
+     */
+    boardPublishLines?: string[];
+    /**
+     * G2 success signal: called with the trigger ids the agent says it actually
+     * drew on for the sent report (parsed from the stripped USED_TRIGGERS
+     * trailer, validated against this window's fires). The wiring records
+     * 'succeeded' outcomes so evolution finally gets a positive signal instead
+     * of being elimination-only. Uncited fires stay NEUTRAL - not failures.
+     */
+    recordTriggerUse?: (triggerIds: string[]) => void;
+}
+export declare class SituationReporter {
+    private windowByChannel;
+    private windowTotal;
+    private fireAgg;
+    private authored;
+    private recalled;
+    private opts;
+    constructor(opts?: SituationReporterOptions);
+    /** Fold a batch of drained events into the bounded per-channel window. */
+    recordWindow(events: OperatorChannelEvent[]): void;
+    /** Fold one fire into the aggregate; merge the memory it recalled (agent-query-driven). */
+    recordFire(activity: FireActivity): void;
+    recordAuthored(count: number): void;
+    /** Any window events, fires, or authored triggers accumulated since the last reset. */
+    hasActivity(): boolean;
+    /**
+     * Agent composes the report from the aggregate; sink delivers it. Returns true if a report was
+     * sent, false if there was nothing to say or the agent suppressed it (NOTHING).
+     */
+    report(askAgent: AskAgent, output: Pick<OutputSink, 'send'>, mode: ReportMode): Promise<boolean>;
+    private reset;
+    /** Public for testability. Aggregate window + fire activity + recalled memory -> agent prompt. */
+    buildPrompt(mode: ReportMode): string;
+}
+//# sourceMappingURL=situation-report.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"situation-report.d.ts","sourceRoot":"","sources":["../../src/operator/situation-report.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACjF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEpD;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,2BAA2B,CAAC;AAEjE,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAChD;AAED,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC;AAqB3C,MAAM,WAAW,wBAAwB;IACvC;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,MAAM,EAAE,CAAC,CAAC;IAC9C;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC7B;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;CACnD;AAKD,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,eAAe,CAAoC;IAC3D,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,IAAI,CAA2B;gBAE3B,IAAI,GAAE,wBAA6B;IAI/C,0EAA0E;IAC1E,YAAY,CAAC,MAAM,EAAE,oBAAoB,EAAE,GAAG,IAAI;IAgBlD,2FAA2F;IAC3F,UAAU,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI;IAmBxC,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAInC,uFAAuF;IACvF,WAAW,IAAI,OAAO;IAItB;;;OAGG;IACG,MAAM,CACV,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,EAChC,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,OAAO,CAAC;IA2CnB,OAAO,CAAC,KAAK;IAQb,kGAAkG;IAClG,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM;CAoHtC"}