@vibe-commit/capture 0.1.0

package/dist/state.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Where the failure policy's decisions are remembered — CR-018.
+ *
+ * `policy.ts` decides; this module persists. The split is what keeps every
+ * classification and both backlog caps testable without a filesystem.
+ *
+ * ## The binding key — `CR-017d`
+ *
+ * `(repoKey, sessionId)`, and the repo half is REQUIRED. `CR-018` shipped this
+ * module keyed on the session alone, deliberately and one dimension short; D58
+ * names what that costs: *"The server key gains repo; the client offset state did
+ * not, so a `prefix_sha256` resync would duplicate repo 1's turns into repo 2."*
+ * The key lives in the path (`sessionStatePath`, which refuses to produce one
+ * without a repo), so there is no bucket for a caller that cannot say which repo
+ * it is in. `files` is untouched — it is already keyed by `FileKey`, which is the
+ * `file_key` of the server's four-column key.
+ *
+ * What `CR-018` needed, and the only reason this module exists a wave early, is
+ * that its three classes are *defined* in terms of an offset: `later` holds one,
+ * `never` advances one, and neither means anything without somewhere to keep it.
+ * `CR-016` left a bootstrap that re-sent from byte 0 every time and said,
+ * correctly, not to build a backlog policy on that. This is the alternative it was
+ * pointing at, kept as thin as the policy allows.
+ *
+ * ## Failure posture
+ *
+ * Every read failure yields the empty state. That direction is a RESYNC — the
+ * client re-sends from offset 0 and the server is idempotent on
+ * `(repo, session, offset)` — rather than a silent skip, which would be data
+ * loss. The one thing lost with it is a recorded `fatal` stop, and a revoked
+ * credential simply 401s again on the next attempt and re-stops.
+ *
+ * Two hooks racing in one session can lose an update to each other. The
+ * consequence is a re-send from a stale offset, which the server treats as a
+ * resync — so this is left unlocked rather than paying for a lockfile on the
+ * hook's wall-clock budget.
+ */
+import { type SessionKey } from "./paths.js";
+import { type FileState } from "./policy.js";
+/** The terminal stop set by the `fatal` class. */
+export interface Stop {
+    readonly at: string;
+    /**
+     * Which credential was refused. Not the credential — a one-way digest of it
+     * (`credentialFingerprint`, `post.ts`).
+     *
+     * This is what makes "stopped until the user reconnects" hold WITHOUT this
+     * module knowing anything about `connect`: reconnecting mints a different
+     * credential, its fingerprint does not match, and capture resumes on its own.
+     * A stop keyed on the session alone would either wedge capture until the
+     * session ended or need a clearing call from a file this task does not own.
+     */
+    readonly fingerprint: string;
+}
+export interface SessionState {
+    /** Monotonic per session, across the main transcript and every sub-agent's. */
+    readonly seq: number;
+    readonly stop: Stop | null;
+    /**
+     * Keyed by `FileKey` — `main`, or `agent-<id>` for a delegated transcript.
+     *
+     * `CR-124` (W6, D76) fills the `agent-*` half. The comment here credited
+     * `CR-020` for a wave; that was wrong — `CR-020`'s finding (D57 §DX7) is
+     * SessionEnd timing only and says nothing about sub-agent files, which is how
+     * the work stayed believed-owned while nothing produced it.
+     *
+     * The SHAPE needed no change to accommodate them, which is why this is a
+     * comment fix and not a migration.
+     */
+    readonly files: Readonly<Record<string, FileState>>;
+}
+export declare const EMPTY_SESSION_STATE: SessionState;
+export declare function loadSessionState(home: string, key: SessionKey): SessionState;
+/** The most recent delivery for one repo, across every session and file. */
+export interface LastSend {
+    /** Epoch ms. */
+    readonly at: number;
+    /** `seq` of the session that delivery belongs to. */
+    readonly seq: number;
+}
+/**
+ * When did this REPO last deliver anything, and at what `seq` — `CR-021`.
+ *
+ * A scan, deliberately, and not a second index. `status` is interactive and has
+ * no `session_id`, so it cannot address a session file the way a hook can; it
+ * knows only the repo. The alternative — a per-repo "latest" pointer written on
+ * every successful send — is a second source of truth for a fact the session
+ * files already hold, and it would be the one that goes stale.
+ *
+ * The directory holds one small JSON per session for one repo, read once per
+ * `status` invocation on a human's keypress. There is no budget here worth
+ * trading correctness for.
+ *
+ * Null means nothing has ever been delivered for this repo. That is distinct
+ * from `at: 0`, which a pre-`CR-021` file parses to — both render as "nothing
+ * recorded yet" rather than as a date.
+ */
+export declare function lastSendForRepo(home: string, repoKey: string): LastSend | null;
+/** Persist. Returns false on any failure — the caller must not throw from a hook. */
+export declare function saveSessionState(home: string, key: SessionKey, next: SessionState): boolean;
+export declare function fileState(session: SessionState, fileKey: string): FileState;
+export declare function withFileState(session: SessionState, fileKey: string, next: FileState): SessionState;
+/**
+ * Is this session stopped for THIS credential?
+ *
+ * A stop recorded against a different fingerprint does not apply: that is the
+ * user having reconnected.
+ */
+export declare function isStopped(session: SessionState, fingerprint: string): boolean;

package/dist/state.js

@@ -0,0 +1,217 @@
+/**
+ * Where the failure policy's decisions are remembered — CR-018.
+ *
+ * `policy.ts` decides; this module persists. The split is what keeps every
+ * classification and both backlog caps testable without a filesystem.
+ *
+ * ## The binding key — `CR-017d`
+ *
+ * `(repoKey, sessionId)`, and the repo half is REQUIRED. `CR-018` shipped this
+ * module keyed on the session alone, deliberately and one dimension short; D58
+ * names what that costs: *"The server key gains repo; the client offset state did
+ * not, so a `prefix_sha256` resync would duplicate repo 1's turns into repo 2."*
+ * The key lives in the path (`sessionStatePath`, which refuses to produce one
+ * without a repo), so there is no bucket for a caller that cannot say which repo
+ * it is in. `files` is untouched — it is already keyed by `FileKey`, which is the
+ * `file_key` of the server's four-column key.
+ *
+ * What `CR-018` needed, and the only reason this module exists a wave early, is
+ * that its three classes are *defined* in terms of an offset: `later` holds one,
+ * `never` advances one, and neither means anything without somewhere to keep it.
+ * `CR-016` left a bootstrap that re-sent from byte 0 every time and said,
+ * correctly, not to build a backlog policy on that. This is the alternative it was
+ * pointing at, kept as thin as the policy allows.
+ *
+ * ## Failure posture
+ *
+ * Every read failure yields the empty state. That direction is a RESYNC — the
+ * client re-sends from offset 0 and the server is idempotent on
+ * `(repo, session, offset)` — rather than a silent skip, which would be data
+ * loss. The one thing lost with it is a recorded `fatal` stop, and a revoked
+ * credential simply 401s again on the next attempt and re-stops.
+ *
+ * Two hooks racing in one session can lose an update to each other. The
+ * consequence is a re-send from a stale offset, which the server treats as a
+ * resync — so this is left unlocked rather than paying for a lockfile on the
+ * hook's wall-clock budget.
+ */
+import { chmodSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { repoSessionsDir, sessionStatePath } from "./paths.js";
+import { EMPTY_FILE_STATE } from "./policy.js";
+export const EMPTY_SESSION_STATE = { seq: 0, stop: null, files: {} };
+export function loadSessionState(home, key) {
+    const path = sessionStatePath(home, key);
+    // No repo, no key, no read. Falling back to a session-only file here is the
+    // whole of D58: it is the one path on which two repos share an offset ledger.
+    if (path === null)
+        return EMPTY_SESSION_STATE;
+    return readStateAt(path);
+}
+/** One state file, or the empty state. Every failure yields empty — a RESYNC. */
+function readStateAt(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return EMPTY_SESSION_STATE;
+    }
+    try {
+        return parseSessionState(JSON.parse(raw));
+    }
+    catch {
+        return EMPTY_SESSION_STATE;
+    }
+}
+/**
+ * When did this REPO last deliver anything, and at what `seq` — `CR-021`.
+ *
+ * A scan, deliberately, and not a second index. `status` is interactive and has
+ * no `session_id`, so it cannot address a session file the way a hook can; it
+ * knows only the repo. The alternative — a per-repo "latest" pointer written on
+ * every successful send — is a second source of truth for a fact the session
+ * files already hold, and it would be the one that goes stale.
+ *
+ * The directory holds one small JSON per session for one repo, read once per
+ * `status` invocation on a human's keypress. There is no budget here worth
+ * trading correctness for.
+ *
+ * Null means nothing has ever been delivered for this repo. That is distinct
+ * from `at: 0`, which a pre-`CR-021` file parses to — both render as "nothing
+ * recorded yet" rather than as a date.
+ */
+export function lastSendForRepo(home, repoKey) {
+    const dir = repoSessionsDir(home, repoKey);
+    if (dir === null)
+        return null;
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        // No directory means nothing was ever written for this repo.
+        return null;
+    }
+    let best = null;
+    for (const entry of entries) {
+        if (!entry.endsWith(".json"))
+            continue;
+        const session = readStateAt(join(dir, entry));
+        for (const file of Object.values(session.files)) {
+            if (file.lastSentAt <= 0)
+                continue;
+            if (best === null || file.lastSentAt > best.at) {
+                best = { at: file.lastSentAt, seq: session.seq };
+            }
+        }
+    }
+    return best;
+}
+/** Persist. Returns false on any failure — the caller must not throw from a hook. */
+export function saveSessionState(home, key, next) {
+    const path = sessionStatePath(home, key);
+    // Refusing to write is safe in the direction this module already fails: the
+    // next invocation resyncs from 0. Writing under a placeholder key is not.
+    if (path === null)
+        return false;
+    try {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        writeFileSync(path, `${JSON.stringify(next)}\n`, { mode: 0o600 });
+        // `writeFileSync`'s `mode` is ignored when the file already exists.
+        chmodSync(path, 0o600);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function fileState(session, fileKey) {
+    return session.files[fileKey] ?? EMPTY_FILE_STATE;
+}
+export function withFileState(session, fileKey, next) {
+    return { ...session, files: { ...session.files, [fileKey]: next } };
+}
+/**
+ * Is this session stopped for THIS credential?
+ *
+ * A stop recorded against a different fingerprint does not apply: that is the
+ * user having reconnected.
+ */
+export function isStopped(session, fingerprint) {
+    return session.stop !== null && session.stop.fingerprint === fingerprint;
+}
+/**
+ * Read back a persisted state defensively.
+ *
+ * Hand-written rather than trusted, for the same reason `consent.ts` validates
+ * its allow list: this file lives in the user's home, is edited by nothing but
+ * us, and would still be believed if something else wrote nonsense into it. A
+ * bogus `sentOffset` would silently skip real turns.
+ */
+function parseSessionState(parsed) {
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return EMPTY_SESSION_STATE;
+    }
+    const o = parsed;
+    const files = {};
+    const rawFiles = o.files;
+    if (rawFiles !== null && typeof rawFiles === "object" && !Array.isArray(rawFiles)) {
+        for (const [key, value] of Object.entries(rawFiles)) {
+            const state = parseFileState(value);
+            if (state !== null)
+                files[key] = state;
+        }
+    }
+    return { seq: nonNegative(o.seq), stop: parseStop(o.stop), files };
+}
+function parseStop(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const o = value;
+    if (typeof o.at !== "string" || typeof o.fingerprint !== "string")
+        return null;
+    if (o.fingerprint === "")
+        return null;
+    return { at: o.at, fingerprint: o.fingerprint };
+}
+function parseFileState(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const o = value;
+    const sentOffset = nonNegative(o.sentOffset);
+    const backlog = [];
+    if (Array.isArray(o.backlog)) {
+        let cursor = sentOffset;
+        for (const entry of o.backlog) {
+            if (entry === null || typeof entry !== "object" || Array.isArray(entry))
+                continue;
+            const e = entry;
+            const from = nonNegative(e.from);
+            const to = nonNegative(e.to);
+            const at = nonNegative(e.at);
+            // Contiguity is an invariant of the writer, so a file that breaks it has
+            // been tampered with or half-written. Stop at the break rather than trust
+            // the rest: a non-contiguous backlog makes `pendingBytes` a fiction.
+            if (from !== cursor || to <= from)
+                break;
+            backlog.push({ from, to, at });
+            cursor = to;
+        }
+    }
+    return {
+        sentOffset,
+        backlog,
+        gapBytes: nonNegative(o.gapBytes),
+        gapCount: nonNegative(o.gapCount),
+        // Absent in any file written before `CR-021`. `nonNegative` yields 0, which
+        // this codebase reads as "never sent" rather than as 1 January 1970.
+        lastSentAt: nonNegative(o.lastSentAt),
+    };
+}
+function nonNegative(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0
+        ? Math.floor(value)
+        : 0;
+}
+//# sourceMappingURL=state.js.map

package/dist/state.js.map

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

package/dist/system_message.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The `systemMessage` channel — D57 (plan §DX3), style guide §10.1.
+ *
+ * The only sanctioned way a hook speaks to a human. It renders to the user
+ * **without** entering the agent's context, which is why it is safe and why it
+ * must stay short.
+ *
+ * FOUR states — `CR-023d` added the fourth, and it inverts an assumption the
+ * other three shared.
+ *
+ * **"stdout empty on the happy path" is no longer universally true.** Every
+ * populated-stdout case before `capture_confirmed` was a FAILURE signal, so a
+ * consumer could read "any `systemMessage`" as "something is wrong". That
+ * consumer is now wrong. This is an inversion, not a shape-preserving addition,
+ * which is why it is called out here rather than left to the type.
+ *
+ * **The fourth state is keyed per `(repo, day)`, the other three per session.**
+ * `PreCompact` mints a new `session_id` mid-task, so a per-session key would fire
+ * the one positive message twice in an afternoon and read as a bug; a key with no
+ * day at all would fire once ever, which under-communicates on a daily tool. See
+ * `repoDayNoticePath`.
+ *
+ * ⚠ Two hard constraints from DESIGN.md §13.7/§13.9:
+ *   - stdout carries **exactly one** well-formed JSON object, or nothing.
+ *     **If construction fails for ANY reason → empty stdout. The fallback is
+ *     always silence.**
+ *   - **No SGR escapes inside the string.** It is a JSON field rendered by Claude
+ *     Code's own UI; embedded escapes are undefined behaviour.
+ */
+export type NoticeState = "not_connected" | "credential_revoked" | "unsupported_runtime"
+/** The only POSITIVE state, and the only one not keyed on the session. */
+ | "capture_confirmed";
+export interface NoticeContext {
+    readonly home: string;
+    readonly sessionId: string;
+    /** `process.versions.node`, for the unsupported-runtime state. */
+    readonly nodeVersion: string;
+    /**
+     * `resolveProjectKey()`'s git toplevel — half of `capture_confirmed`'s key.
+     *
+     * Null for the three session-keyed states, which is not a placeholder: two of
+     * them can fire BEFORE the consent gate has resolved a project at all
+     * (`unsupported_runtime` fires before anything else runs). `capture_confirmed`
+     * cannot fire without one and refuses rather than falling back — the same
+     * discipline `CR-017d` applied to the state key, for the same reason.
+     */
+    readonly repoKey: string | null;
+    /**
+     * Injected so the day boundary is reachable from a test. Following
+     * `CommandContext.now`'s precedent; a module that read the clock directly
+     * could only be tested by waiting for midnight.
+     */
+    readonly now: () => Date;
+}
+/**
+ * The UTC calendar day, `YYYY-MM-DD`.
+ *
+ * UTC and not local: a local key silently depends on the machine's timezone and
+ * changes twice a year at a DST boundary, which would fire the message a second
+ * time on one day in spring and skip it on one in autumn. It also matches how
+ * this file already timestamps (`new Date().toISOString()`).
+ */
+export declare function utcDay(now: Date): string;
+/** The one-line text for a state. Never contains an escape sequence. */
+export declare function noticeText(state: NoticeState, nodeVersion: string): string;
+/**
+ * Where this state's once-per-key marker lives, or null if it cannot have one.
+ *
+ * The whole difference between the four states is here: three are keyed on the
+ * session, and `capture_confirmed` is keyed on `(repo, day)`.
+ *
+ * Null when `capture_confirmed` has no repo. **Refuse, do not guess** — a
+ * fallback key would be shared by every repo on the machine, so the first repo
+ * to capture today would silence all the others. Null becomes silence, which is
+ * this channel's fallback everywhere else too.
+ */
+export declare function noticeClaimPath(ctx: NoticeContext, state: NoticeState): string | null;
+/**
+ * Claim the once-per-KEY slot for `state`.
+ *
+ * `wx` is doing real work here: it creates-or-fails atomically, so two hooks
+ * firing concurrently under the same key cannot both win. A read-then-write
+ * check would let both through and print the message twice. That mattered for
+ * one session; it matters more now, because `capture_confirmed`'s key spans a
+ * whole day and therefore many more concurrent hooks.
+ *
+ * Returns false on ANY failure, including an unwritable home. A message we cannot
+ * record having sent is a message we do not send — repeating it every turn is
+ * worse than losing it once.
+ */
+export declare function claimSessionNotice(ctx: NoticeContext, state: NoticeState): boolean;
+/**
+ * Render the hook's stdout payload for a state, or null.
+ *
+ * Null means "write nothing", and every failure resolves to null. The caller
+ * writes the string verbatim and adds a trailing newline; it never builds JSON
+ * itself, so there is exactly one place this contract can be broken.
+ */
+export declare function renderNotice(ctx: NoticeContext, state: NoticeState): string | null;
+/** True if `text` holds any C0 control character (including ESC) or DEL. */
+export declare function hasControlCharacter(text: string): boolean;

package/dist/system_message.js

@@ -0,0 +1,141 @@
+/**
+ * The `systemMessage` channel — D57 (plan §DX3), style guide §10.1.
+ *
+ * The only sanctioned way a hook speaks to a human. It renders to the user
+ * **without** entering the agent's context, which is why it is safe and why it
+ * must stay short.
+ *
+ * FOUR states — `CR-023d` added the fourth, and it inverts an assumption the
+ * other three shared.
+ *
+ * **"stdout empty on the happy path" is no longer universally true.** Every
+ * populated-stdout case before `capture_confirmed` was a FAILURE signal, so a
+ * consumer could read "any `systemMessage`" as "something is wrong". That
+ * consumer is now wrong. This is an inversion, not a shape-preserving addition,
+ * which is why it is called out here rather than left to the type.
+ *
+ * **The fourth state is keyed per `(repo, day)`, the other three per session.**
+ * `PreCompact` mints a new `session_id` mid-task, so a per-session key would fire
+ * the one positive message twice in an afternoon and read as a bug; a key with no
+ * day at all would fire once ever, which under-communicates on a daily tool. See
+ * `repoDayNoticePath`.
+ *
+ * ⚠ Two hard constraints from DESIGN.md §13.7/§13.9:
+ *   - stdout carries **exactly one** well-formed JSON object, or nothing.
+ *     **If construction fails for ANY reason → empty stdout. The fallback is
+ *     always silence.**
+ *   - **No SGR escapes inside the string.** It is a JSON field rendered by Claude
+ *     Code's own UI; embedded escapes are undefined behaviour.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { SYSTEM_MESSAGE, URLS } from "./copy/index.js";
+import { repoDayNoticePath, sessionNoticePath } from "./paths.js";
+import { NODE_FLOOR_TEXT } from "./runtime.js";
+/**
+ * The UTC calendar day, `YYYY-MM-DD`.
+ *
+ * UTC and not local: a local key silently depends on the machine's timezone and
+ * changes twice a year at a DST boundary, which would fire the message a second
+ * time on one day in spring and skip it on one in autumn. It also matches how
+ * this file already timestamps (`new Date().toISOString()`).
+ */
+export function utcDay(now) {
+    return now.toISOString().slice(0, 10);
+}
+/** The one-line text for a state. Never contains an escape sequence. */
+export function noticeText(state, nodeVersion) {
+    switch (state) {
+        case "not_connected":
+            return SYSTEM_MESSAGE.notConnected;
+        case "credential_revoked":
+            return SYSTEM_MESSAGE.credentialRevoked;
+        case "unsupported_runtime":
+            return SYSTEM_MESSAGE.unsupportedRuntime(NODE_FLOOR_TEXT, nodeVersion);
+        case "capture_confirmed":
+            return SYSTEM_MESSAGE.captureConfirmed(URLS.dashboard);
+    }
+}
+/**
+ * Where this state's once-per-key marker lives, or null if it cannot have one.
+ *
+ * The whole difference between the four states is here: three are keyed on the
+ * session, and `capture_confirmed` is keyed on `(repo, day)`.
+ *
+ * Null when `capture_confirmed` has no repo. **Refuse, do not guess** — a
+ * fallback key would be shared by every repo on the machine, so the first repo
+ * to capture today would silence all the others. Null becomes silence, which is
+ * this channel's fallback everywhere else too.
+ */
+export function noticeClaimPath(ctx, state) {
+    if (state !== "capture_confirmed") {
+        return sessionNoticePath(ctx.home, ctx.sessionId, state);
+    }
+    if (ctx.repoKey === null || ctx.repoKey === "")
+        return null;
+    return repoDayNoticePath(ctx.home, ctx.repoKey, utcDay(ctx.now()), state);
+}
+/**
+ * Claim the once-per-KEY slot for `state`.
+ *
+ * `wx` is doing real work here: it creates-or-fails atomically, so two hooks
+ * firing concurrently under the same key cannot both win. A read-then-write
+ * check would let both through and print the message twice. That mattered for
+ * one session; it matters more now, because `capture_confirmed`'s key spans a
+ * whole day and therefore many more concurrent hooks.
+ *
+ * Returns false on ANY failure, including an unwritable home. A message we cannot
+ * record having sent is a message we do not send — repeating it every turn is
+ * worse than losing it once.
+ */
+export function claimSessionNotice(ctx, state) {
+    const path = noticeClaimPath(ctx, state);
+    if (path === null)
+        return false;
+    try {
+        mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+        writeFileSync(path, `${JSON.stringify({ at: new Date().toISOString() })}\n`, {
+            flag: "wx",
+            mode: 0o600,
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Render the hook's stdout payload for a state, or null.
+ *
+ * Null means "write nothing", and every failure resolves to null. The caller
+ * writes the string verbatim and adds a trailing newline; it never builds JSON
+ * itself, so there is exactly one place this contract can be broken.
+ */
+export function renderNotice(ctx, state) {
+    try {
+        const text = noticeText(state, ctx.nodeVersion);
+        // A message carrying an escape sequence or a newline is undefined behaviour
+        // in Claude Code's renderer, so it is dropped rather than sent — silence is
+        // the fallback. Tested by char code, not by a regex holding a literal
+        // control character: DESIGN.md §13.2 puts every escape sequence in one
+        // module, and a literal one here would be both a violation and unreadable.
+        if (hasControlCharacter(text))
+            return null;
+        if (!claimSessionNotice(ctx, state))
+            return null;
+        return JSON.stringify({ systemMessage: text });
+    }
+    catch {
+        return null;
+    }
+}
+/** True if `text` holds any C0 control character (including ESC) or DEL. */
+export function hasControlCharacter(text) {
+    for (let i = 0; i < text.length; i += 1) {
+        const code = text.charCodeAt(i);
+        if (code < 0x20 || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=system_message.js.map

package/dist/system_message.js.map

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