charness 0.0.0-stage → 3.0.0

package/dist/scheduler/store.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maxRemindersPerThread = exports.maxSchedulesPerThread = void 0;
+exports.slugify = slugify;
+exports.generateScheduleId = generateScheduleId;
+exports.createScheduleRecord = createScheduleRecord;
+exports.createScheduleForThread = createScheduleForThread;
+const node_crypto_1 = require("node:crypto");
+const sessionKey_1 = require("../sessionKey");
+const deliveryKind_1 = require("./deliveryKind");
+const recurrence_1 = require("./recurrence");
+/**
+ * @description Scheduler store helpers — id generation and the cap-enforcing
+ * create path. The persisted collection itself lives on {@link StateStore}
+ * (`schedules` field + getters/setters), following the `traceConfig` pattern;
+ * this module owns the bits the store shouldn't know about: how an id is
+ * minted from a name, and the per-thread cap of each delivery kind.
+ */
+/**
+ * Hard cap on the AGENT's schedules per thread — prompt jobs (no `deliveryKind`)
+ * and checks, i.e. everything but reminders. Enforced in
+ * {@link createScheduleForThread}. This cap exists FOR the agent: `schedule_create`
+ * is in the model's hands and a looping one can mint junk jobs, so 30 is the muzzle.
+ */
+exports.maxSchedulesPerThread = 30;
+/**
+ * Hard cap on `/reminders` schedules per thread, counted SEPARATELY from
+ * {@link maxSchedulesPerThread} so neither creator can eat the other's slots.
+ * It is far higher because a reminder costs four button taps — a human cannot
+ * mint 100 by accident — and bounded at all only because every record lives in
+ * the single `state.json` (rewritten whole on every change) and arms one timer at
+ * boot, so a runaway code path must not be able to write records without end.
+ */
+exports.maxRemindersPerThread = 100;
+/** Length of the random suffix appended to a slug to keep ids unique. */
+const idSuffixLength = 6;
+/** Max characters kept from the slugified name before the suffix. */
+const slugMaxLength = 40;
+/**
+ * @description Turn a free-text name into a lowercase ascii-ish slug: lowercase,
+ * non-alphanumerics collapsed to single hyphens, edge hyphens trimmed, bounded
+ * length. Returns `'job'` as a stable fallback when nothing usable survives
+ * (e.g. a name of only emoji/punctuation) so an id is always well-formed.
+ */
+function slugify(name) {
+    const slug = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+/, '')
+        .replace(/-+$/, '')
+        .slice(0, slugMaxLength)
+        .replace(/-+$/, '');
+    return slug || 'job';
+}
+/**
+ * @description Mint a schedule id: `slugify(name)` + `-` + a 6-char lowercase
+ * alphanumeric random suffix. The suffix makes the id collision-resistant
+ * without the create-time uniqueness check the spec calls out as bad UX.
+ */
+function generateScheduleId(name) {
+    // base36 of random bytes yields [0-9a-z]; pad+slice to a fixed-length suffix.
+    const suffix = (0, node_crypto_1.randomBytes)(8).toString('hex');
+    const alnum = parseInt(suffix, 16).toString(36).padStart(idSuffixLength, '0').slice(-idSuffixLength);
+    return `${slugify(name)}-${alnum}`;
+}
+/**
+ * @description Build a fresh {@link ScheduleRecord} from its inputs, computing
+ * the initial `nextRunAt` for the spec. Pure (besides id randomness): callers
+ * pass `nowMs` so creation time and the first `nextRunAt` are deterministic in
+ * tests. Does NOT persist — the caller (or {@link createScheduleForThread})
+ * writes it to the store.
+ */
+function createScheduleRecord(args) {
+    const { threadKey, name, spec, prompt, createdBy, nowMs, lastAdapterName, isPinSilent } = args;
+    const nowIso = new Date(nowMs).toISOString();
+    const record = {
+        id: generateScheduleId(name),
+        threadKey: (0, sessionKey_1.keyToString)(threadKey),
+        name,
+        spec,
+        prompt,
+        createdBy,
+        createdAt: nowIso,
+        updatedAt: nowIso,
+        nextRunAt: (0, recurrence_1.getNextRunAt)(spec, nowMs),
+    };
+    if (lastAdapterName !== undefined)
+        record.lastAdapterName = lastAdapterName;
+    if (isPinSilent)
+        record.isPinSilent = true;
+    // Absent means the agent-prompt kind, so the field is written only when set.
+    if (args.deliveryKind !== undefined)
+        record.deliveryKind = args.deliveryKind;
+    if (args.checkCommand !== undefined)
+        record.checkCommand = args.checkCommand;
+    if (args.checkTimeoutSec !== undefined)
+        record.checkTimeoutSec = args.checkTimeoutSec;
+    return record;
+}
+/**
+ * @description Create and persist a schedule for a thread, enforcing the cap of
+ * the record's OWN delivery kind: a reminder counts only the thread's reminders
+ * against {@link maxRemindersPerThread}, an agent-prompt job only the thread's
+ * agent-prompt jobs against {@link maxSchedulesPerThread}. Counting the kinds
+ * apart is what keeps each rejection actionable — a shared counter let the two
+ * steal slots from each other and told the agent it had hit a limit it could not
+ * reach, because `schedule_list` hides reminders and `schedule_cancel` refuses
+ * their ids. `limit` in the result is the one that actually applied, since callers
+ * render it.
+ */
+async function createScheduleForThread(store, args) {
+    const isReminder = (0, deliveryKind_1.checkIsReminderSchedule)(args);
+    const limit = isReminder ? exports.maxRemindersPerThread : exports.maxSchedulesPerThread;
+    const sameKindCount = store
+        .getThreadSchedules(args.threadKey)
+        .filter((record) => (0, deliveryKind_1.checkIsReminderSchedule)(record) === isReminder).length;
+    if (sameKindCount >= limit) {
+        return { ok: false, reason: 'cap-reached', limit };
+    }
+    const record = createScheduleRecord(args);
+    await store.upsertSchedule(record);
+    return { ok: true, record };
+}
+//# sourceMappingURL=store.js.map

package/dist/scheduler/store.js.map

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

package/dist/scheduler/timezoneRecompute.d.ts

@@ -0,0 +1,61 @@
+import type { StateStore } from '../state';
+import type { SchedulerEngine } from './engine';
+/**
+ * @description Re-base every scheduled job after the operator changes the
+ * instance timezone.
+ *
+ * Why this cannot just call the engine's `rearmAll()`: that is the BOOT replay.
+ * It arms each job from its STORED `nextRunAt`, and a `nextRunAt` already in the
+ * past is treated as a MISSED run — it fires a catch-up, announcing and pinning
+ * "missed at HH:MM" into the topic and delivering the prompt to the agent. After
+ * a zone change a stored `nextRunAt` is routinely in the past (moving from UTC
+ * to a zone three hours ahead puts every job earlier than it was), so `rearmAll`
+ * would spam bogus catch-ups for runs that were never actually missed.
+ *
+ * The correct sequence is recompute FIRST, then arm: each job's next occurrence
+ * is derived from `now` under the new zone (cron expressions are wall-clock, so
+ * "every day at 9am" stays 9am and simply lands on a different instant), the
+ * fresh value is persisted, and only then is the timer armed — at a strictly
+ * future instant, which the engine never mistakes for a missed run.
+ *
+ * PAUSED jobs are recomputed too. They are skipped by the arm step (the engine
+ * leaves a paused job disarmed by design), but their stored `nextRunAt` must
+ * still move: otherwise a later resume would arm a stale pre-change instant.
+ */
+/**
+ * @name TimezoneRecomputeDeps
+ * @description Everything the recompute needs from the outside world, injected
+ * so it is testable against a fake store and a real engine with a fake clock —
+ * the only way to assert the load-bearing property, that NO delivery fires.
+ */
+export interface TimezoneRecomputeDeps {
+    store: Pick<StateStore, 'getSchedules' | 'upsertSchedule' | 'removeSchedule' | 'flush'>;
+    engine: Pick<SchedulerEngine, 'armJob' | 'disarmJob'>;
+    /** Current epoch ms. Injected so tests run on a fake clock. */
+    now: () => number;
+}
+/**
+ * @name TimezoneRecomputeResult
+ * @description What the pass did, for the `/timezone` confirmation line.
+ * `recomputed` counts jobs whose `nextRunAt` was re-derived and persisted;
+ * `removed` counts jobs dropped because the new computation left no future
+ * occurrence at all.
+ */
+export interface TimezoneRecomputeResult {
+    recomputed: number;
+    removed: number;
+}
+/**
+ * @description Recompute + re-arm every persisted job for the new timezone.
+ *
+ * Per job the decision is {@link getRebindResumeAction} — the SAME rule the
+ * rebind path already applies, deliberately reused rather than restated: derive
+ * the next occurrence strictly from `now`, and drop the record when there is
+ * none (an expired one-shot has no future instant, so it cannot be re-armed and
+ * must not linger as a husk).
+ *
+ * A job's `isPaused` / `pauseReason` are preserved untouched — this pass changes
+ * WHEN a job runs, never WHETHER it is active.
+ */
+export declare function recomputeSchedulesForTimezoneChange(deps: TimezoneRecomputeDeps): Promise<TimezoneRecomputeResult>;
+//# sourceMappingURL=timezoneRecompute.d.ts.map

package/dist/scheduler/timezoneRecompute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timezoneRecompute.d.ts","sourceRoot":"","sources":["../../src/scheduler/timezoneRecompute.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAGhD;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,cAAc,GAAG,gBAAgB,GAAG,gBAAgB,GAAG,OAAO,CAAC,CAAC;IACxF,MAAM,EAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,GAAG,WAAW,CAAC,CAAC;IACtD,+DAA+D;IAC/D,GAAG,EAAE,MAAM,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,mCAAmC,CACvD,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,uBAAuB,CAAC,CA8BlC"}

package/dist/scheduler/timezoneRecompute.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.recomputeSchedulesForTimezoneChange = recomputeSchedulesForTimezoneChange;
+const rebindResume_1 = require("./rebindResume");
+/**
+ * @description Recompute + re-arm every persisted job for the new timezone.
+ *
+ * Per job the decision is {@link getRebindResumeAction} — the SAME rule the
+ * rebind path already applies, deliberately reused rather than restated: derive
+ * the next occurrence strictly from `now`, and drop the record when there is
+ * none (an expired one-shot has no future instant, so it cannot be re-armed and
+ * must not linger as a husk).
+ *
+ * A job's `isPaused` / `pauseReason` are preserved untouched — this pass changes
+ * WHEN a job runs, never WHETHER it is active.
+ */
+async function recomputeSchedulesForTimezoneChange(deps) {
+    const { store, engine, now } = deps;
+    const nowMs = now();
+    const records = Object.values(store.getSchedules());
+    let recomputed = 0;
+    let removed = 0;
+    for (const record of records) {
+        const action = (0, rebindResume_1.getRebindResumeAction)(record, nowMs);
+        if (action.kind === 'remove') {
+            await store.removeSchedule(record.id);
+            engine.disarmJob(record.id);
+            removed += 1;
+            continue;
+        }
+        const updated = {
+            ...record,
+            nextRunAt: action.nextRunAt,
+            updatedAt: new Date(nowMs).toISOString(),
+        };
+        await store.upsertSchedule(updated);
+        // `armJob` is the single arming authority: it leaves a paused record
+        // disarmed, so paused jobs get the fresh `nextRunAt` without waking up.
+        engine.armJob(updated);
+        recomputed += 1;
+    }
+    if (records.length > 0)
+        await store.flush();
+    return { recomputed, removed };
+}
+//# sourceMappingURL=timezoneRecompute.js.map

package/dist/scheduler/timezoneRecompute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timezoneRecompute.js","sourceRoot":"","sources":["../../src/scheduler/timezoneRecompute.ts"],"names":[],"mappings":";;AAiEA,kFAgCC;AAhGD,iDAAuD;AAoDvD;;;;;;;;;;;GAWG;AACI,KAAK,UAAU,mCAAmC,CACvD,IAA2B;IAE3B,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;IACpC,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC;IACpB,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC,CAAC;IAEpD,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,OAAO,GAAG,CAAC,CAAC;IAEhB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,MAAM,GAAG,IAAA,oCAAqB,EAAC,MAAM,EAAE,KAAK,CAAC,CAAC;QACpD,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,MAAM,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACtC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YAC5B,OAAO,IAAI,CAAC,CAAC;YACb,SAAS;QACX,CAAC;QACD,MAAM,OAAO,GAAmB;YAC9B,GAAG,MAAM;YACT,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,SAAS,EAAE,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,WAAW,EAAE;SACzC,CAAC;QACF,MAAM,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;QACpC,qEAAqE;QACrE,wEAAwE;QACxE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACvB,UAAU,IAAI,CAAC,CAAC;IAClB,CAAC;IAED,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;QAAE,MAAM,KAAK,CAAC,KAAK,EAAE,CAAC;IAC5C,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC;AACjC,CAAC"}

package/dist/scheduler/types.d.ts

@@ -0,0 +1,139 @@
+/**
+ * @description Shared scheduler types. Lives in its own file because the spec
+ * union and the persisted record are consumed by `recurrence.ts` (S1),
+ * `store.ts` (S2) and the engine/delivery layers (later scopes).
+ */
+/**
+ * @name ScheduleSpec
+ * @description When a scheduled job fires.
+ *
+ * - `cron`: a 5-field host-local cron expression. May carry `remainingRuns`
+ *   to make it an N-times job — the engine decrements it after each fire and
+ *   deletes the record when it reaches zero.
+ * - `once`: a single absolute instant (ISO 8601 string). Fires once, then the
+ *   record is deleted.
+ *
+ * `remainingRuns` deliberately rides ONLY the `cron` kind: a `once` job is by
+ * definition a single run, so an N-times one-shot is meaningless.
+ */
+export type ScheduleSpec = {
+    kind: 'cron';
+    cronExpr: string;
+    remainingRuns?: number;
+} | {
+    kind: 'once';
+    onceAtIso: string;
+};
+/** Who created a schedule — a human via `/schedule`, or the agent via an MCP tool. */
+export type ScheduleCreatedBy = 'user' | 'agent';
+/**
+ * @name ScheduleDeliveryKind
+ * @description WHAT a fire does, for the kinds that are not the original
+ * agent-prompt delivery:
+ *  - `'reminder'` — a bot-LOCAL job whose whole delivery is the announcement +
+ *    its pin (no session started, none touched).
+ *  - `'check'` — a watchdog: the bot runs {@link ScheduleRecord.checkCommand} in
+ *    the bound folder, stays silent while it passes, and on the first failure
+ *    pins an alert and wakes the agent with `prompt` (see `checkRun.ts`).
+ */
+export type ScheduleDeliveryKind = 'reminder' | 'check';
+/**
+ * Outcome of the most recent fire, persisted for `/schedule list` display.
+ *  - `delivered`      — prompt reached the agent.
+ *  - `skipped-overlap`— the previous fire was still in its delivery pipeline.
+ *  - `failed`         — delivery threw and could not be completed.
+ */
+export type ScheduleLastRunStatus = 'delivered' | 'skipped-overlap' | 'failed';
+/** Why a job is paused. Only reason in v1 is an unbound topic (see plan S8). */
+export type SchedulePauseReason = 'unbound';
+/**
+ * @name ScheduleRecord
+ * @description One persisted scheduled job. Shape locked in plan S2.
+ *
+ * `nextRunAt` is the crash-critical field: the engine arms a timer to it and
+ * `state.flush()`es after every fire so a restart never re-fires or loses a run.
+ * `lastAdapterName` snapshots the adapter to start after a rebind when the
+ * thread has no live session.
+ */
+export interface ScheduleRecord {
+    /** `slugify(name)` + '-' + short random suffix. Unique within the store. */
+    id: string;
+    /** Owning thread, serialised `"<chatId>:<threadId>"`. */
+    threadKey: string;
+    /** Human-facing job name (free text supplied by user/agent). */
+    name: string;
+    spec: ScheduleSpec;
+    /**
+     * The text the fire delivers: forwarded to the agent as the prompt for an
+     * agent-prompt job, POSTED into the topic as the message for a reminder, and
+     * forwarded to the agent after the failure details when a check fails. One
+     * field for every kind on purpose — a second text field would need a state
+     * migration and could disagree with this one.
+     */
+    prompt: string;
+    createdBy: ScheduleCreatedBy;
+    /** ISO 8601 creation timestamp. */
+    createdAt: string;
+    /** ISO 8601 timestamp of the last mutation. */
+    updatedAt: string;
+    /** Epoch ms of the next scheduled occurrence, or `null` when exhausted. */
+    nextRunAt: number | null;
+    /** Epoch ms of the last fire, absent until the first one. */
+    lastRunAt?: number;
+    lastRunStatus?: ScheduleLastRunStatus;
+    /** True while paused (e.g. topic unbound); the engine disarms paused jobs. */
+    isPaused?: boolean;
+    pauseReason?: SchedulePauseReason;
+    /**
+     * Pin the fire announcement WITHOUT notifying group members. Default
+     * (absent/false) notifies everyone — user decision 2026-06-06; the agent
+     * sets this from the user's phrasing via `schedule_create.isPinSilent`.
+     */
+    isPinSilent?: boolean;
+    /** Adapter name to start when delivering with no live session after a rebind. */
+    lastAdapterName?: string;
+    /**
+     * The delivery kind, ABSENT for the original agent-prompt behaviour. Optional
+     * rather than required precisely so no persisted job needs migrating: every
+     * record written before reminders existed keeps firing exactly as it did, and
+     * "no kind recorded" can only ever mean the prompt path.
+     */
+    deliveryKind?: ScheduleDeliveryKind;
+    /** The shell command a `'check'` job runs in the bound folder; exit 0 passes. */
+    checkCommand?: string;
+    /** Seconds a `'check'` run may take before it is stopped and counted as failed. */
+    checkTimeoutSec?: number;
+    /**
+     * True from the failed check run that raised the alert until a run passes
+     * again. Persisted so a restart neither repeats the alert nor forgets to say
+     * the check recovered.
+     */
+    isCheckFailing?: boolean;
+}
+/**
+ * @name FireContext
+ * @description Passed by the engine to the `deliver` callback so the
+ * announcement can annotate a missed run.
+ *
+ *  - `on-time` — fired at (or within tolerance of) its scheduled instant.
+ *  - `catch-up` — replayed once at boot for a run missed while the bot was
+ *    down; `missedAtMs` carries the original due instant so the announcement
+ *    can render the "missed at HH:MM" note.
+ */
+export interface FireContext {
+    kind: 'on-time' | 'catch-up';
+    /** Original due instant (epoch ms) for a catch-up fire. */
+    missedAtMs?: number;
+}
+/**
+ * @name DeliveryOutcome
+ * @description Result of one delivery attempt, returned by the `deliver`
+ * callback (the real implementation lands in `delivery.ts`, S4). The engine
+ * maps `status` onto the record's `lastRunStatus` and the ledger end record.
+ * `error` carries a readable failure message when `status === 'failed'`.
+ */
+export interface DeliveryOutcome {
+    status: 'delivered' | 'failed';
+    error?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/scheduler/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/scheduler/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAExC,sFAAsF;AACtF,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,CAAC;AAEjD;;;;;;;;;GASG;AACH,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,OAAO,CAAC;AAExD;;;;;GAKG;AACH,MAAM,MAAM,qBAAqB,GAAG,WAAW,GAAG,iBAAiB,GAAG,QAAQ,CAAC;AAE/E,gFAAgF;AAChF,MAAM,MAAM,mBAAmB,GAAG,SAAS,CAAC;AAE5C;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,EAAE,EAAE,MAAM,CAAC;IACX,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,YAAY,CAAC;IACnB;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,iBAAiB,CAAC;IAC7B,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,qBAAqB,CAAC;IACtC,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,mBAAmB,CAAC;IAClC;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,iFAAiF;IACjF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,YAAY,CAAC,EAAE,oBAAoB,CAAC;IACpC,iFAAiF;IACjF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,mFAAmF;IACnF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,SAAS,GAAG,UAAU,CAAC;IAC7B,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,WAAW,GAAG,QAAQ,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/scheduler/types.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * @description Shared scheduler types. Lives in its own file because the spec
+ * union and the persisted record are consumed by `recurrence.ts` (S1),
+ * `store.ts` (S2) and the engine/delivery layers (later scopes).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/scheduler/types.js.map

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

package/dist/sendErrorClassifier.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @description Classify Telegram API errors raised by `sendMessage` /
+ * `editMessageText` / `deleteMessage` so the bot can take the right
+ * cleanup action without confusing reversible events (a closed topic)
+ * with irreversible ones (a deleted topic).
+ *
+ * Plan §13.10 / E5:
+ *   - **thread-deleted** (400 "message thread not found") → wipe binding +
+ *     agents + in-memory state.
+ *   - **topic-closed** (400 "TOPIC_CLOSED" / "topic is closed") → keep the
+ *     binding, mark `closed: true`, surface a friendly note.
+ *   - **everything else** → log and leave state alone.
+ *
+ * Extracted from `bot.ts` so the classification rules are unit-testable
+ * without importing the rest of the Telegraf bot (plan §11 Этап 7 / R8).
+ */
+/** Shape of the bits we read out of a Telegram API error object. */
+export interface TelegramApiErrorLike {
+    response?: {
+        error_code?: number;
+        description?: string;
+        parameters?: {
+            retry_after?: number;
+        };
+    };
+    description?: string;
+}
+export type SendErrorClass = 'thread-deleted' | 'topic-closed' | 'other';
+export declare function checkIsApiError(e: unknown): e is TelegramApiErrorLike;
+export declare function getErrorCode(e: TelegramApiErrorLike): number | undefined;
+export declare function getErrorDescription(e: TelegramApiErrorLike): string;
+/**
+ * @description The `retry_after` (seconds) Telegram attaches to a 429, or
+ * `undefined` when absent. Callers fall back to their own default backoff when
+ * this is missing.
+ */
+export declare function getErrorRetryAfterSeconds(e: TelegramApiErrorLike): number | undefined;
+/**
+ * @description Map an arbitrary error into one of the cleanup categories
+ * the bot knows about. Returns `'other'` for anything that doesn't match
+ * (and for non-API errors) so callers can fall through to a generic
+ * "log and ignore" branch without crashing.
+ */
+export declare function classifySendError(err: unknown): SendErrorClass;
+//# sourceMappingURL=sendErrorClassifier.d.ts.map

package/dist/sendErrorClassifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sendErrorClassifier.d.ts","sourceRoot":"","sources":["../src/sendErrorClassifier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,oEAAoE;AACpE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE;YAAE,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;IAChG,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,cAAc,GAAG,gBAAgB,GAAG,cAAc,GAAG,OAAO,CAAC;AAEzE,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,oBAAoB,CASrE;AAED,wBAAgB,YAAY,CAAC,CAAC,EAAE,oBAAoB,GAAG,MAAM,GAAG,SAAS,CAExE;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,oBAAoB,GAAG,MAAM,CAEnE;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,oBAAoB,GAAG,MAAM,GAAG,SAAS,CAErF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAQ9D"}

package/dist/sendErrorClassifier.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * @description Classify Telegram API errors raised by `sendMessage` /
+ * `editMessageText` / `deleteMessage` so the bot can take the right
+ * cleanup action without confusing reversible events (a closed topic)
+ * with irreversible ones (a deleted topic).
+ *
+ * Plan §13.10 / E5:
+ *   - **thread-deleted** (400 "message thread not found") → wipe binding +
+ *     agents + in-memory state.
+ *   - **topic-closed** (400 "TOPIC_CLOSED" / "topic is closed") → keep the
+ *     binding, mark `closed: true`, surface a friendly note.
+ *   - **everything else** → log and leave state alone.
+ *
+ * Extracted from `bot.ts` so the classification rules are unit-testable
+ * without importing the rest of the Telegraf bot (plan §11 Этап 7 / R8).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkIsApiError = checkIsApiError;
+exports.getErrorCode = getErrorCode;
+exports.getErrorDescription = getErrorDescription;
+exports.getErrorRetryAfterSeconds = getErrorRetryAfterSeconds;
+exports.classifySendError = classifySendError;
+function checkIsApiError(e) {
+    // Telegraf surfaces both `err.response` (the raw payload) and a flat
+    // `err.description` on different code paths; accept either as proof
+    // that this is the kind of error we know how to classify.
+    return (typeof e === 'object' &&
+        e !== null &&
+        ('response' in e || 'description' in e));
+}
+function getErrorCode(e) {
+    return e.response?.error_code;
+}
+function getErrorDescription(e) {
+    return (e.response?.description ?? e.description ?? '').toString();
+}
+/**
+ * @description The `retry_after` (seconds) Telegram attaches to a 429, or
+ * `undefined` when absent. Callers fall back to their own default backoff when
+ * this is missing.
+ */
+function getErrorRetryAfterSeconds(e) {
+    return e.response?.parameters?.retry_after;
+}
+/**
+ * @description Map an arbitrary error into one of the cleanup categories
+ * the bot knows about. Returns `'other'` for anything that doesn't match
+ * (and for non-API errors) so callers can fall through to a generic
+ * "log and ignore" branch without crashing.
+ */
+function classifySendError(err) {
+    if (!checkIsApiError(err))
+        return 'other';
+    const code = getErrorCode(err);
+    if (code !== 400)
+        return 'other';
+    const desc = getErrorDescription(err);
+    if (/thread not found/i.test(desc))
+        return 'thread-deleted';
+    if (/TOPIC_CLOSED|topic is closed/i.test(desc))
+        return 'topic-closed';
+    return 'other';
+}
+//# sourceMappingURL=sendErrorClassifier.js.map

package/dist/sendErrorClassifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sendErrorClassifier.js","sourceRoot":"","sources":["../src/sendErrorClassifier.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;AAUH,0CASC;AAED,oCAEC;AAED,kDAEC;AAOD,8DAEC;AAQD,8CAQC;AA1CD,SAAgB,eAAe,CAAC,CAAU;IACxC,qEAAqE;IACrE,oEAAoE;IACpE,0DAA0D;IAC1D,OAAO,CACL,OAAO,CAAC,KAAK,QAAQ;QACrB,CAAC,KAAK,IAAI;QACV,CAAC,UAAU,IAAI,CAAC,IAAI,aAAa,IAAI,CAAC,CAAC,CACxC,CAAC;AACJ,CAAC;AAED,SAAgB,YAAY,CAAC,CAAuB;IAClD,OAAO,CAAC,CAAC,QAAQ,EAAE,UAAU,CAAC;AAChC,CAAC;AAED,SAAgB,mBAAmB,CAAC,CAAuB;IACzD,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE,WAAW,IAAI,CAAC,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC;AACrE,CAAC;AAED;;;;GAIG;AACH,SAAgB,yBAAyB,CAAC,CAAuB;IAC/D,OAAO,CAAC,CAAC,QAAQ,EAAE,UAAU,EAAE,WAAW,CAAC;AAC7C,CAAC;AAED;;;;;GAKG;AACH,SAAgB,iBAAiB,CAAC,GAAY;IAC5C,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC;IAC1C,MAAM,IAAI,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;IAC/B,IAAI,IAAI,KAAK,GAAG;QAAE,OAAO,OAAO,CAAC;IACjC,MAAM,IAAI,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,gBAAgB,CAAC;IAC5D,IAAI,+BAA+B,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,cAAc,CAAC;IACtE,OAAO,OAAO,CAAC;AACjB,CAAC"}