@hera-al/server 1.6.7 → 1.6.11

package/dist/cron/cron-service.d.ts

@@ -8,6 +8,10 @@ export type CronServiceOpts = {
     enabled: boolean;
     defaultTimezone?: string;
     onExecute: (job: CronJob) => Promise<CronExecuteResult>;
+    /** Optional: prune stale cron sessions from SessionDB. */
+    sessionReaper?: {
+        pruneStaleSessions: (maxAgeMs: number) => number;
+    };
 };
 export type CronStatusSummary = {
     enabled: boolean;
@@ -20,22 +24,46 @@ export declare class CronService {
     private timer;
     private running;
     private op;
+    private lastReaperSweepAtMs;
     private readonly storePath;
     private readonly enabled;
     private readonly defaultTimezone;
     private readonly onExecute;
+    private readonly sessionReaper?;
     constructor(opts: CronServiceOpts);
     private locked;
     private ensureLoaded;
     private persist;
+    private computeStaggeredCronNextRunAtMs;
     private computeJobNextRunAtMs;
+    /**
+     * Safe wrapper for schedule computation. Returns `true` if value changed.
+     * On error, increments scheduleErrorCount and auto-disables after MAX_SCHEDULE_ERRORS.
+     */
+    private safeRecomputeJobNextRunAtMs;
+    /**
+     * Full recompute: recomputes nextRunAtMs for all enabled jobs.
+     * Use only at start() when we need a clean baseline.
+     */
     private recomputeNextRuns;
+    /**
+     * Maintenance-only recompute: handles disabled jobs and stuck markers,
+     * but does NOT recompute nextRunAtMs for enabled jobs that already have a value.
+     * Prevents silently advancing past-due nextRunAtMs without execution.
+     * (OpenClaw #13992, #17852)
+     */
+    private recomputeNextRunsForMaintenance;
     private nextWakeAtMs;
     private armTimer;
     private stopTimer;
     private onTimer;
-    private runDueJobs;
-    private executeJob;
+    private findDueJobs;
+    /** Resolve the effective timeout for a job (per-job override or global default). */
+    private resolveJobTimeoutMs;
+    /** Execute onExecute with a safety-net timeout (OpenClaw DEFAULT_JOB_TIMEOUT_MS). */
+    private executeWithTimeout;
+    private applyJobResult;
+    private sweepStaleSessions;
     start(): Promise<void>;
     stop(): void;
     status(): Promise<CronStatusSummary>;
@@ -53,5 +81,11 @@ export declare class CronService {
         ran: boolean;
         reason?: string;
     }>;
+    /**
+     * After restart, find and execute jobs that were due during downtime.
+     * Skips one-shot ("at") jobs that already ran at least once.
+     * (OpenClaw runMissedJobs)
+     */
+    private runMissedJobs;
 }
 //# sourceMappingURL=cron-service.d.ts.map

package/dist/cron/cron-service.js

@@ -1 +1 @@
-import t from"node:crypto";import{computeNextRunAtMs as e}from"./schedule.js";import{loadCronStore as s,saveCronStore as n}from"./store.js";import{createLogger as a}from"../utils/logger.js";const i=a("Cron"),o=t=>t.then(()=>{},()=>{});export class CronService{store=null;timer=null;running=!1;op=Promise.resolve();storePath;enabled;defaultTimezone;onExecute;constructor(t){this.storePath=t.storePath,this.enabled=t.enabled,this.defaultTimezone=t.defaultTimezone||"",this.onExecute=t.onExecute}async locked(t){const e=o(this.op).then(t),s=o(e);return this.op=s,await e}async ensureLoaded(t){this.store&&!t?.forceReload||(this.store=await s(this.storePath))}async persist(){this.store&&await n(this.storePath,this.store)}computeJobNextRunAtMs(t,s){if(t.enabled){if("at"===t.schedule.kind){if("ok"===t.state.lastStatus&&t.state.lastRunAtMs)return;const e=new Date(t.schedule.at).getTime();return Number.isFinite(e)?e:void 0}return e(t.schedule,s,this.defaultTimezone)}}recomputeNextRuns(){if(!this.store)return;const t=Date.now();for(const e of this.store.jobs){if(e.state||(e.state={}),!e.enabled){e.state.nextRunAtMs=void 0,e.state.runningAtMs=void 0;continue}const s=e.state.runningAtMs;"number"==typeof s&&t-s>72e5&&(i.warn(`Clearing stuck running marker for job ${e.id}`),e.state.runningAtMs=void 0),e.state.nextRunAtMs=this.computeJobNextRunAtMs(e,t)}}nextWakeAtMs(){const t=(this.store?.jobs??[]).filter(t=>t.enabled&&"number"==typeof t.state.nextRunAtMs);if(0!==t.length)return t.reduce((t,e)=>Math.min(t,e.state.nextRunAtMs),t[0].state.nextRunAtMs)}armTimer(){if(this.timer&&clearTimeout(this.timer),this.timer=null,!this.enabled)return;const t=this.nextWakeAtMs();if(!t)return;const e=Math.max(t-Date.now(),0),s=Math.min(e,2147483647);this.timer=setTimeout(()=>{this.onTimer().catch(t=>{i.error(`Timer tick failed: ${t}`)})},s)}stopTimer(){this.timer&&clearTimeout(this.timer),this.timer=null}async onTimer(){if(!this.running){this.running=!0;try{await this.locked(async()=>{await this.ensureLoaded({forceReload:!0}),await this.runDueJobs(),this.recomputeNextRuns(),await this.persist()})}finally{this.running=!1,this.armTimer()}}}async runDueJobs(){if(!this.store)return;const t=Date.now(),e=this.store.jobs.filter(e=>{if(!e.enabled)return!1;if("number"==typeof e.state.runningAtMs)return!1;const s=e.state.nextRunAtMs;return"number"==typeof s&&t>=s});for(const t of e)await this.executeJob(t,{forced:!1})}async executeJob(t,e){const s=Date.now();t.state.runningAtMs=s,t.state.lastError=void 0;let n=!1;const a=async(e,a)=>{const i=Date.now();t.state.runningAtMs=void 0,t.state.lastRunAtMs=s,t.state.lastStatus=e,t.state.lastDurationMs=Math.max(0,i-s),t.state.lastError=a;const o="at"===t.schedule.kind&&"ok"===e&&!0===t.deleteAfterRun;o||("at"===t.schedule.kind&&"ok"===e?(t.enabled=!1,t.state.nextRunAtMs=void 0):t.enabled?t.state.nextRunAtMs=this.computeJobNextRunAtMs(t,i):t.state.nextRunAtMs=void 0),o&&this.store&&(this.store.jobs=this.store.jobs.filter(e=>e.id!==t.id),n=!0)};try{i.info(`Executing job "${t.name}" (${t.id})`);const e=(await this.onExecute(t)).delivered?"ok (delivered)":"ok (suppressed)";i.info(`Job "${t.name}" finished: ${e}`),await a("ok")}catch(e){i.error(`Job "${t.name}" failed: ${e}`),await a("error",String(e))}finally{t.updatedAtMs=Date.now(),e.forced||!t.enabled||n||(t.state.nextRunAtMs=this.computeJobNextRunAtMs(t,Date.now()))}}async start(){await this.locked(async()=>{this.enabled?(await this.ensureLoaded(),this.recomputeNextRuns(),await this.persist(),this.armTimer(),i.info(`Cron started (${this.store?.jobs.length??0} jobs, next wake: ${this.nextWakeAtMs()??"none"})`)):i.info("Cron disabled")})}stop(){this.stopTimer()}async status(){return await this.locked(async()=>(await this.ensureLoaded(),{enabled:this.enabled,storePath:this.storePath,jobs:this.store?.jobs.length??0,nextWakeAtMs:this.enabled?this.nextWakeAtMs()??null:null}))}async list(t){return await this.locked(async()=>{await this.ensureLoaded();const e=!0===t?.includeDisabled;return[...(this.store?.jobs??[]).filter(t=>e||t.enabled)].sort((t,e)=>(t.state.nextRunAtMs??0)-(e.state.nextRunAtMs??0))})}async add(e){return await this.locked(async()=>{await this.ensureLoaded();const s=Date.now(),n=t.randomUUID(),a="boolean"==typeof e.deleteAfterRun?e.deleteAfterRun:"at"===e.schedule.kind||void 0,o="boolean"!=typeof e.enabled||e.enabled,r="boolean"!=typeof e.isolated||e.isolated,d={id:n,name:e.name.trim()||"Untitled",description:e.description?.trim()||void 0,enabled:o,isolated:r,deleteAfterRun:a,suppressToken:e.suppressToken,createdAtMs:s,updatedAtMs:s,schedule:e.schedule,channel:e.channel,chatId:e.chatId,message:e.message,state:{...e.state}};return d.state.nextRunAtMs=this.computeJobNextRunAtMs(d,s),this.store?.jobs.push(d),await this.persist(),this.armTimer(),i.info(`Job added: "${d.name}" (${d.id}), next run: ${d.state.nextRunAtMs??"none"}`),d})}async update(t,e){return await this.locked(async()=>{await this.ensureLoaded();const s=this.store?.jobs.find(e=>e.id===t);if(!s)throw new Error(`Unknown cron job id: ${t}`);const n=Date.now();return"name"in e&&"string"==typeof e.name&&(s.name=e.name.trim()||s.name),"description"in e&&(s.description=e.description?.trim()||void 0),"boolean"==typeof e.enabled&&(s.enabled=e.enabled),"boolean"==typeof e.isolated&&(s.isolated=e.isolated),"boolean"==typeof e.deleteAfterRun&&(s.deleteAfterRun=e.deleteAfterRun),"boolean"==typeof e.suppressToken&&(s.suppressToken=e.suppressToken),e.schedule&&(s.schedule=e.schedule),"string"==typeof e.channel&&(s.channel=e.channel),"string"==typeof e.chatId&&(s.chatId=e.chatId),"string"==typeof e.message&&(s.message=e.message),e.state&&(s.state={...s.state,...e.state}),s.updatedAtMs=n,s.enabled?s.state.nextRunAtMs=this.computeJobNextRunAtMs(s,n):(s.state.nextRunAtMs=void 0,s.state.runningAtMs=void 0),await this.persist(),this.armTimer(),s})}async remove(t){return await this.locked(async()=>{if(await this.ensureLoaded(),!this.store)return{ok:!1,removed:!1};const e=this.store.jobs.length;this.store.jobs=this.store.jobs.filter(e=>e.id!==t);const s=this.store.jobs.length!==e;return await this.persist(),this.armTimer(),s&&i.info(`Job removed: ${t}`),{ok:!0,removed:s}})}async run(t,e){return await this.locked(async()=>{await this.ensureLoaded();const s=this.store?.jobs.find(e=>e.id===t);if(!s)throw new Error(`Unknown cron job id: ${t}`);const n=Date.now(),a="force"===e;return a||s.enabled&&"number"==typeof s.state.nextRunAtMs&&n>=s.state.nextRunAtMs?(await this.executeJob(s,{forced:a}),await this.persist(),this.armTimer(),{ok:!0,ran:!0}):{ok:!0,ran:!1,reason:"not-due"}})}}
+import e from"node:crypto";import{computeNextRunAtMs as t}from"./schedule.js";import{loadCronStore as s,saveCronStore as n}from"./store.js";import{createLogger as r}from"../utils/logger.js";const o=r("Cron"),i=72e5,a=[3e4,6e4,3e5,9e5,36e5];function u(e){return"number"==typeof e.staggerMs&&Number.isFinite(e.staggerMs)?Math.max(0,Math.floor(e.staggerMs)):function(e){const t=e.trim().split(/\s+/).filter(Boolean);if(5===t.length){const[e,s]=t;return"0"===e&&s.includes("*")}if(6===t.length){const[e,s,n]=t;return"0"===e&&"0"===s&&n.includes("*")}return!1}(e.expr)?3e5:0}const d=e=>e.then(()=>{},()=>{});export class CronService{store=null;timer=null;running=!1;op=Promise.resolve();lastReaperSweepAtMs=0;storePath;enabled;defaultTimezone;onExecute;sessionReaper;constructor(e){this.storePath=e.storePath,this.enabled=e.enabled,this.defaultTimezone=e.defaultTimezone||"",this.onExecute=e.onExecute,this.sessionReaper=e.sessionReaper}async locked(e){const t=d(this.op).then(e),s=d(t);return this.op=s,await t}async ensureLoaded(e){this.store&&!e?.forceReload||(this.store=await s(this.storePath))}async persist(){this.store&&await n(this.storePath,this.store)}computeStaggeredCronNextRunAtMs(s,n){if("cron"!==s.schedule.kind)return t(s.schedule,n,this.defaultTimezone);const r=u(s.schedule),o=function(t,s){return s<=1?0:e.createHash("sha256").update(t).digest().readUInt32BE(0)%s}(s.id,r);if(o<=0)return t(s.schedule,n,this.defaultTimezone);let i=Math.max(0,n-o);for(let e=0;e<4;e+=1){const e=t(s.schedule,i,this.defaultTimezone);if(void 0===e)return;const r=e+o;if(r>n)return r;i=Math.max(i+1,e+1e3)}}computeJobNextRunAtMs(e,s){if(e.enabled){if("at"===e.schedule.kind){if("ok"===e.state.lastStatus&&e.state.lastRunAtMs)return;const t=new Date(e.schedule.at).getTime();return Number.isFinite(t)?t:void 0}if("cron"===e.schedule.kind){const t=this.computeStaggeredCronNextRunAtMs(e,s);if(void 0===t){const t=1e3*Math.floor(s/1e3)+1e3;return this.computeStaggeredCronNextRunAtMs(e,t)}return t}return t(e.schedule,s,this.defaultTimezone)}}safeRecomputeJobNextRunAtMs(e,t){let s=!1;try{const n=this.computeJobNextRunAtMs(e,t);e.state.nextRunAtMs!==n&&(e.state.nextRunAtMs=n,s=!0),e.state.scheduleErrorCount&&(e.state.scheduleErrorCount=void 0,s=!0)}catch(t){const n=(e.state.scheduleErrorCount??0)+1;e.state.scheduleErrorCount=n,e.state.nextRunAtMs=void 0,e.state.lastError=`schedule error: ${String(t)}`,s=!0,n>=3?(e.enabled=!1,o.error(`Auto-disabled job "${e.name}" after ${n} schedule errors: ${t}`)):o.warn(`Schedule compute error for "${e.name}" (${n}/3): ${t}`)}return s}recomputeNextRuns(){if(!this.store)return;const e=Date.now();for(const t of this.store.jobs){if(t.state||(t.state={}),!t.enabled){t.state.nextRunAtMs=void 0,t.state.runningAtMs=void 0;continue}const s=t.state.runningAtMs;"number"==typeof s&&e-s>i&&(o.warn(`Clearing stuck running marker for job ${t.id}`),t.state.runningAtMs=void 0),this.safeRecomputeJobNextRunAtMs(t,e)}}recomputeNextRunsForMaintenance(){if(!this.store)return!1;const e=Date.now();let t=!1;for(const s of this.store.jobs){if(s.state||(s.state={},t=!0),!s.enabled){void 0!==s.state.nextRunAtMs&&(s.state.nextRunAtMs=void 0,t=!0),void 0!==s.state.runningAtMs&&(s.state.runningAtMs=void 0,t=!0);continue}const n=s.state.runningAtMs;"number"==typeof n&&e-n>i&&(o.warn(`Clearing stuck running marker for job ${s.id}`),s.state.runningAtMs=void 0,t=!0),void 0===s.state.nextRunAtMs&&this.safeRecomputeJobNextRunAtMs(s,e)&&(t=!0)}return t}nextWakeAtMs(){const e=(this.store?.jobs??[]).filter(e=>e.enabled&&"number"==typeof e.state.nextRunAtMs);if(0!==e.length)return e.reduce((e,t)=>Math.min(e,t.state.nextRunAtMs),e[0].state.nextRunAtMs)}armTimer(){if(this.timer&&clearTimeout(this.timer),this.timer=null,!this.enabled)return;const e=this.nextWakeAtMs();if(!e)return;const t=Math.max(e-Date.now(),0),s=Math.min(t,6e4);this.timer=setTimeout(()=>{this.onTimer().catch(e=>{o.error(`Timer tick failed: ${e}`)})},s)}stopTimer(){this.timer&&clearTimeout(this.timer),this.timer=null}async onTimer(){if(this.running)return this.timer&&clearTimeout(this.timer),void(this.timer=setTimeout(()=>{this.onTimer().catch(e=>{o.error(`Timer tick failed: ${e}`)})},6e4));this.running=!0;try{const e=await this.locked(async()=>{await this.ensureLoaded({forceReload:!0});const e=this.findDueJobs();if(0===e.length){return this.recomputeNextRunsForMaintenance()&&await this.persist(),[]}const t=Date.now();for(const s of e)s.state.runningAtMs=t,s.state.lastError=void 0;return await this.persist(),e}),t=[];for(const s of e){const e=Date.now();try{o.info(`Executing job "${s.name}" (${s.id})`);const n=await this.executeWithTimeout(s),r=n.delivered?"ok (delivered)":"ok (suppressed)";o.info(`Job "${s.name}" finished: ${r}`),t.push({job:s,status:"ok",delivered:n.delivered,startedAt:e,endedAt:Date.now()})}catch(n){o.error(`Job "${s.name}" failed: ${n}`),t.push({job:s,status:"error",error:String(n),delivered:!1,startedAt:e,endedAt:Date.now()})}}t.length>0&&await this.locked(async()=>{await this.ensureLoaded({forceReload:!0});for(const e of t){const t=this.store?.jobs.find(t=>t.id===e.job.id);t&&this.applyJobResult(t,e)}this.recomputeNextRunsForMaintenance(),await this.persist()}),this.sweepStaleSessions()}finally{this.running=!1,this.armTimer()}}findDueJobs(){if(!this.store)return[];const e=Date.now();return this.store.jobs.filter(t=>{if(!t.enabled)return!1;if("number"==typeof t.state.runningAtMs)return!1;const s=t.state.nextRunAtMs;return"number"==typeof s&&e>=s})}resolveJobTimeoutMs(e){if("number"==typeof e.timeoutSeconds){if(e.timeoutSeconds<=0)return;return Math.floor(1e3*e.timeoutSeconds)}return 6e5}async executeWithTimeout(e){const t=this.resolveJobTimeoutMs(e);if(void 0===t)return this.onExecute(e);let s;try{return await Promise.race([this.onExecute(e),new Promise((n,r)=>{s=setTimeout(()=>r(new Error(`cron: job "${e.name}" timed out after ${t/1e3}s`)),t)})])}finally{s&&clearTimeout(s)}}applyJobResult(e,t){e.state.runningAtMs=void 0,e.state.lastRunAtMs=t.startedAt,e.state.lastStatus=t.status,e.state.lastDurationMs=Math.max(0,t.endedAt-t.startedAt),e.state.lastError=t.error,e.updatedAtMs=t.endedAt,"error"===t.status?e.state.consecutiveErrors=(e.state.consecutiveErrors??0)+1:e.state.consecutiveErrors=0;const s="at"===e.schedule.kind&&"ok"===t.status&&!0===e.deleteAfterRun;if(!s)if("at"===e.schedule.kind)e.enabled=!1,e.state.nextRunAtMs=void 0;else if("error"===t.status&&e.enabled){const s=e.state.consecutiveErrors??1,n=Math.min(s-1,a.length-1),r=a[Math.max(0,n)],i=this.computeJobNextRunAtMs(e,t.endedAt),u=t.endedAt+r;e.state.nextRunAtMs=void 0!==i?Math.max(i,u):u,o.info(`Job "${e.name}" error backoff: ${s} consecutive errors, next retry in ${r/1e3}s`)}else if(e.enabled){const s=this.computeJobNextRunAtMs(e,t.endedAt);if("cron"===e.schedule.kind){const n=t.endedAt+2e3;e.state.nextRunAtMs=void 0!==s?Math.max(s,n):n}else e.state.nextRunAtMs=s}else e.state.nextRunAtMs=void 0;s&&this.store&&(this.store.jobs=this.store.jobs.filter(t=>t.id!==e.id))}sweepStaleSessions(){if(!this.sessionReaper)return;const e=Date.now();if(!(e-this.lastReaperSweepAtMs<3e5)){this.lastReaperSweepAtMs=e;try{const e=this.sessionReaper.pruneStaleSessions(864e5);e>0&&o.info(`Session reaper: pruned ${e} stale cron session(s)`)}catch(e){o.warn(`Session reaper sweep failed: ${e}`)}}}async start(){await this.locked(async()=>{this.enabled?(await this.ensureLoaded(),this.recomputeNextRuns(),await this.persist(),this.armTimer(),o.info(`Cron started (${this.store?.jobs.length??0} jobs, next wake: ${this.nextWakeAtMs()??"none"})`)):o.info("Cron disabled")}),this.enabled&&await this.runMissedJobs()}stop(){this.stopTimer()}async status(){return this.store||await this.locked(async()=>{await this.ensureLoaded()}),{enabled:this.enabled,storePath:this.storePath,jobs:this.store?.jobs.length??0,nextWakeAtMs:this.enabled?this.nextWakeAtMs()??null:null}}async list(e){this.store||await this.locked(async()=>{await this.ensureLoaded()});const t=!0===e?.includeDisabled;return[...(this.store?.jobs??[]).filter(e=>t||e.enabled)].sort((e,t)=>(e.state.nextRunAtMs??0)-(t.state.nextRunAtMs??0))}async add(t){return await this.locked(async()=>{await this.ensureLoaded();const s=Date.now(),n=e.randomUUID(),r="boolean"==typeof t.deleteAfterRun?t.deleteAfterRun:"at"===t.schedule.kind||void 0,i="boolean"!=typeof t.enabled||t.enabled,a="boolean"!=typeof t.isolated||t.isolated,u={id:n,name:t.name.trim()||"Untitled",description:t.description?.trim()||void 0,enabled:i,isolated:a,deleteAfterRun:r,suppressToken:t.suppressToken,timeoutSeconds:t.timeoutSeconds,createdAtMs:s,updatedAtMs:s,schedule:t.schedule,channel:t.channel,chatId:t.chatId,message:t.message,state:{...t.state}};return u.state.nextRunAtMs=this.computeJobNextRunAtMs(u,s),this.store?.jobs.push(u),await this.persist(),this.armTimer(),o.info(`Job added: "${u.name}" (${u.id}), next run: ${u.state.nextRunAtMs??"none"}`),u})}async update(e,t){return await this.locked(async()=>{await this.ensureLoaded();const s=this.store?.jobs.find(t=>t.id===e);if(!s)throw new Error(`Unknown cron job id: ${e}`);const n=Date.now();return"name"in t&&"string"==typeof t.name&&(s.name=t.name.trim()||s.name),"description"in t&&(s.description=t.description?.trim()||void 0),"boolean"==typeof t.enabled&&(s.enabled=t.enabled),"boolean"==typeof t.isolated&&(s.isolated=t.isolated),"boolean"==typeof t.deleteAfterRun&&(s.deleteAfterRun=t.deleteAfterRun),"boolean"==typeof t.suppressToken&&(s.suppressToken=t.suppressToken),"number"==typeof t.timeoutSeconds&&(s.timeoutSeconds=t.timeoutSeconds),t.schedule&&(s.schedule=t.schedule),"string"==typeof t.channel&&(s.channel=t.channel),"string"==typeof t.chatId&&(s.chatId=t.chatId),"string"==typeof t.message&&(s.message=t.message),t.state&&(s.state={...s.state,...t.state}),s.updatedAtMs=n,s.enabled?s.state.nextRunAtMs=this.computeJobNextRunAtMs(s,n):(s.state.nextRunAtMs=void 0,s.state.runningAtMs=void 0),await this.persist(),this.armTimer(),s})}async remove(e){return await this.locked(async()=>{if(await this.ensureLoaded(),!this.store)return{ok:!1,removed:!1};const t=this.store.jobs.length;this.store.jobs=this.store.jobs.filter(t=>t.id!==e);const s=this.store.jobs.length!==t;return await this.persist(),this.armTimer(),s&&o.info(`Job removed: ${e}`),{ok:!0,removed:s}})}async run(e,t){const s=await this.locked(async()=>{await this.ensureLoaded();const s=this.store?.jobs.find(t=>t.id===e);if(!s)throw new Error(`Unknown cron job id: ${e}`);const n=Date.now();return"force"===t||s.enabled&&"number"==typeof s.state.nextRunAtMs&&n>=s.state.nextRunAtMs?(s.state.runningAtMs=n,s.state.lastError=void 0,await this.persist(),s):null});if(!s)return{ok:!0,ran:!1,reason:"not-due"};const n=Date.now();let r,i="ok";try{o.info(`Executing job "${s.name}" (${s.id}) [manual run]`);const e=(await this.executeWithTimeout(s)).delivered?"ok (delivered)":"ok (suppressed)";o.info(`Job "${s.name}" finished: ${e}`)}catch(e){o.error(`Job "${s.name}" failed: ${e}`),i="error",r=String(e)}return await this.locked(async()=>{await this.ensureLoaded({forceReload:!0});const e=this.store?.jobs.find(e=>e.id===s.id);e&&this.applyJobResult(e,{status:i,error:r,startedAt:n,endedAt:Date.now()}),this.recomputeNextRunsForMaintenance(),await this.persist(),this.armTimer()}),{ok:!0,ran:!0}}async runMissedJobs(){const e=await this.locked(async()=>{if(await this.ensureLoaded(),!this.store)return[];const e=Date.now();return this.store.jobs.filter(t=>{if(!t.enabled)return!1;if("number"==typeof t.state.runningAtMs)return!1;if("at"===t.schedule.kind&&t.state.lastStatus)return!1;const s=t.state.nextRunAtMs;return"number"==typeof s&&e>=s})});if(0!==e.length){o.info(`Running ${e.length} missed job(s) after restart: ${e.map(e=>e.name).join(", ")}`);for(const t of e){const e=Date.now();t.state.runningAtMs=e,t.state.lastError=void 0;let s,n="ok";try{o.info(`Executing missed job "${t.name}" (${t.id})`);const e=(await this.executeWithTimeout(t)).delivered?"ok (delivered)":"ok (suppressed)";o.info(`Missed job "${t.name}" finished: ${e}`)}catch(e){o.error(`Missed job "${t.name}" failed: ${e}`),n="error",s=String(e)}await this.locked(async()=>{await this.ensureLoaded({forceReload:!0});const r=this.store?.jobs.find(e=>e.id===t.id);r&&this.applyJobResult(r,{status:n,error:s,startedAt:e,endedAt:Date.now()}),this.recomputeNextRunsForMaintenance(),await this.persist(),this.armTimer()})}}}}

package/dist/cron/types.d.ts

@@ -9,6 +9,7 @@ export type CronSchedule = {
     kind: "cron";
     expr: string;
     tz?: string;
+    staggerMs?: number;
 };
 export type CronJobState = {
     nextRunAtMs?: number;
@@ -17,6 +18,9 @@ export type CronJobState = {
     lastStatus?: "ok" | "error" | "skipped";
     lastError?: string;
     lastDurationMs?: number;
+    consecutiveErrors?: number;
+    /** How many times schedule computation failed in a row (auto-disable after 3). */
+    scheduleErrorCount?: number;
 };
 export type CronJob = {
     id: string;
@@ -26,6 +30,8 @@ export type CronJob = {
     isolated: boolean;
     deleteAfterRun?: boolean;
     suppressToken: boolean;
+    /** Per-job execution timeout in seconds. 0 = no timeout. Defaults to DEFAULT_JOB_TIMEOUT_MS. */
+    timeoutSeconds?: number;
     createdAtMs: number;
     updatedAtMs: number;
     schedule: CronSchedule;

package/dist/gateway/bridge.d.ts

@@ -28,7 +28,7 @@ export interface ChannelAdapter {
     start(onMessage: MessageHandler): Promise<void>;
     sendText(chatId: string, text: string): Promise<void>;
     sendAudio?(chatId: string, filePath: string, asVoice?: boolean): Promise<void>;
-    sendButtons?(chatId: string, text: string, buttons: InlineButton[]): Promise<void>;
+    sendButtons?(chatId: string, text: string, buttons: InlineButton[][]): Promise<void>;
     setTyping?(chatId: string): Promise<void>;
     clearTyping?(chatId: string): Promise<void>;
     /** Cooperative typing release: decrements refcount instead of force-clearing. */

package/dist/gateway/channel-manager.d.ts

@@ -11,7 +11,7 @@ export declare class ChannelManager {
     startAll(): Promise<void>;
     sendToChannel(channelName: string, chatId: string, text: string): Promise<void>;
     sendAudio(channelName: string, chatId: string, filePath: string, asVoice?: boolean): Promise<void>;
-    sendButtons(channelName: string, chatId: string, text: string, buttons: InlineButton[]): Promise<void>;
+    sendButtons(channelName: string, chatId: string, text: string, buttons: InlineButton[][]): Promise<void>;
     setTyping(channelName: string, chatId: string): Promise<void>;
     clearTyping(channelName: string, chatId: string): Promise<void>;
     /**

package/dist/gateway/channel-manager.js

@@ -1 +1 @@
-import{parseMediaLines as t}from"../utils/media-response.js";import{createLogger as e}from"../utils/logger.js";const s=e("ChannelManager");export class ChannelManager{config;tokenDb;onMessage;adapters=new Map;constructor(t,e,s){this.config=t,this.tokenDb=e,this.onMessage=s}registerAdapter(t){this.adapters.set(t.name,t)}async startAll(){const t=[];for(const[e,n]of this.adapters)s.info(`Starting channel: ${e}`),t.push(n.start(this.onMessage).then(()=>{s.info(`Channel started: ${e}`)}).catch(t=>{s.error(`Failed to start channel ${e}: ${t}`)}));await Promise.allSettled(t)}async sendToChannel(t,e,n){const a=this.adapters.get(t);a?await a.sendText(e,n):s.error(`Channel not found: ${t}`)}async sendAudio(t,e,n,a){const r=this.adapters.get(t);r?r.sendAudio?await r.sendAudio(e,n,a):s.warn(`Channel ${t} does not support audio, skipping`):s.error(`Channel not found: ${t}`)}async sendButtons(t,e,n,a){const r=this.adapters.get(t);if(r)if(r.sendButtons)await r.sendButtons(e,n,a);else{const t=a.map((t,e)=>`${e+1}. ${t.text}`).join("\n");await r.sendText(e,`${n}\n\n${t}\n\nReply with your choice or type your answer.`)}else s.error(`Channel not found: ${t}`)}async setTyping(t,e){const s=this.adapters.get(t);if(s&&s.setTyping)try{await s.setTyping(e)}catch{}}async clearTyping(t,e){const s=this.adapters.get(t);if(s&&s.clearTyping)try{await s.clearTyping(e)}catch{}}async releaseTyping(t,e){const s=this.adapters.get(t);if(s)if(s.releaseTyping)try{await s.releaseTyping(e)}catch{}else if(s.clearTyping)try{await s.clearTyping(e)}catch{}}async sendResponse(e,n,a){const{textParts:r,mediaEntries:o}=t(a);for(const t of o)try{await this.sendAudio(e,n,t.path,t.asVoice)}catch(t){s.error(`Failed to send audio to ${e}:${n}: ${t}`)}const i=r.join("\n").trim();i&&await this.sendToChannel(e,n,i)}getAdapter(t){return this.adapters.get(t)}getChannel(t){return this.adapters.get(t)}async sendSystemMessage(t,e,n){const a=this.adapters.get(t);if(a)try{await a.sendText(e,n),s.debug(`System message sent to ${t}:${e}`)}catch(n){s.error(`Failed to send system message to ${t}:${e}: ${n}`)}else s.warn(`Cannot send system message: channel ${t} not found`)}listAdapters(){return[...this.adapters.entries()].map(([t])=>({name:t,active:!0}))}async stopAll(){const t=[];for(const[e,n]of this.adapters)s.info(`Stopping channel: ${e}`),t.push(n.stop().catch(t=>{s.error(`Error stopping channel ${e}: ${t}`)}));await Promise.allSettled(t)}}
+import{parseMediaLines as t}from"../utils/media-response.js";import{createLogger as e}from"../utils/logger.js";const s=e("ChannelManager");export class ChannelManager{config;tokenDb;onMessage;adapters=new Map;constructor(t,e,s){this.config=t,this.tokenDb=e,this.onMessage=s}registerAdapter(t){this.adapters.set(t.name,t)}async startAll(){const t=[];for(const[e,a]of this.adapters)s.info(`Starting channel: ${e}`),t.push(a.start(this.onMessage).then(()=>{s.info(`Channel started: ${e}`)}).catch(t=>{s.error(`Failed to start channel ${e}: ${t}`)}));await Promise.allSettled(t)}async sendToChannel(t,e,a){const n=this.adapters.get(t);n?await n.sendText(e,a):s.error(`Channel not found: ${t}`)}async sendAudio(t,e,a,n){const r=this.adapters.get(t);r?r.sendAudio?await r.sendAudio(e,a,n):s.warn(`Channel ${t} does not support audio, skipping`):s.error(`Channel not found: ${t}`)}async sendButtons(t,e,a,n){const r=this.adapters.get(t);if(r)if(r.sendButtons)await r.sendButtons(e,a,n);else{const t=n.flat().map((t,e)=>`${e+1}. ${t.text}`).join("\n");await r.sendText(e,`${a}\n\n${t}\n\nReply with your choice or type your answer.`)}else s.error(`Channel not found: ${t}`)}async setTyping(t,e){const s=this.adapters.get(t);if(s&&s.setTyping)try{await s.setTyping(e)}catch{}}async clearTyping(t,e){const s=this.adapters.get(t);if(s&&s.clearTyping)try{await s.clearTyping(e)}catch{}}async releaseTyping(t,e){const s=this.adapters.get(t);if(s)if(s.releaseTyping)try{await s.releaseTyping(e)}catch{}else if(s.clearTyping)try{await s.clearTyping(e)}catch{}}async sendResponse(e,a,n){const{textParts:r,mediaEntries:o}=t(n);for(const t of o)try{await this.sendAudio(e,a,t.path,t.asVoice)}catch(t){s.error(`Failed to send audio to ${e}:${a}: ${t}`)}const i=r.join("\n").trim();i&&await this.sendToChannel(e,a,i)}getAdapter(t){return this.adapters.get(t)}getChannel(t){return this.adapters.get(t)}async sendSystemMessage(t,e,a){const n=this.adapters.get(t);if(n)try{await n.sendText(e,a),s.debug(`System message sent to ${t}:${e}`)}catch(a){s.error(`Failed to send system message to ${t}:${e}: ${a}`)}else s.warn(`Cannot send system message: channel ${t} not found`)}listAdapters(){return[...this.adapters.entries()].map(([t])=>({name:t,active:!0}))}async stopAll(){const t=[];for(const[e,a]of this.adapters)s.info(`Stopping channel: ${e}`),t.push(a.stop().catch(t=>{s.error(`Error stopping channel ${e}: ${t}`)}));await Promise.allSettled(t)}}

package/dist/gateway/channels/telegram/config-types.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Telegram configuration types and schemas
+ *
+ * This module re-exports types from the main config and defines
+ * additional types used by the modular Telegram implementation.
+ */
+import type { TelegramAccountConfig, TelegramActionConfig, TelegramRetryConfig, TelegramInlineButtonsScope } from "../../../config.js";
+export type { TelegramAccountConfig, TelegramActionConfig, TelegramRetryConfig, TelegramInlineButtonsScope, };
+/** Button style for Telegram inline keyboards */
+export type TelegramButtonStyle = "danger" | "success" | "primary";
+/** Inline button definition */
+export interface TelegramInlineButton {
+    text: string;
+    callback_data: string;
+    style?: TelegramButtonStyle;
+}
+/** Inline buttons - array of button rows */
+export type TelegramInlineButtons = TelegramInlineButton[][];
+/** Chat type detection result */
+export type TelegramChatType = "direct" | "group" | "unknown";
+/** Result from send operations */
+export interface TelegramSendResult {
+    messageId: string;
+    chatId: string;
+}
+/** Result from poll send operations */
+export interface TelegramPollSendResult extends TelegramSendResult {
+    pollId?: string;
+}
+/** Options for sending messages */
+export interface TelegramSendOptions {
+    token?: string;
+    accountId?: string;
+    mediaUrl?: string;
+    buttons?: TelegramInlineButtons;
+    replyToMessageId?: number;
+    messageThreadId?: number;
+    quoteText?: string;
+    asVoice?: boolean;
+    silent?: boolean;
+    retry?: TelegramRetryConfig;
+    linkPreview?: boolean;
+    textChunkLimit?: number;
+}
+/** Options for sending polls */
+export interface TelegramPollOptions {
+    question: string;
+    options: string[];
+    maxSelections?: number;
+    durationSeconds?: number;
+    isAnonymous?: boolean;
+    replyToMessageId?: number;
+    messageThreadId?: number;
+}
+/** Options for reaction operations */
+export interface TelegramReactOptions {
+    remove?: boolean;
+    retry?: TelegramRetryConfig;
+}
+/** Result from reaction operations */
+export interface TelegramReactResult {
+    ok: boolean;
+    warning?: string;
+}
+/** Options for edit operations */
+export interface TelegramEditOptions {
+    buttons?: TelegramInlineButtons;
+    linkPreview?: boolean;
+}
+/** Result from edit operations */
+export interface TelegramEditResult {
+    ok: boolean;
+    messageId: string;
+    chatId: string;
+}
+/** Result from delete operations */
+export interface TelegramDeleteResult {
+    ok: boolean;
+}
+/** Cached sticker metadata */
+export interface CachedSticker {
+    fileId: string;
+    fileUniqueId: string;
+    emoji?: string;
+    setName?: string;
+    description: string;
+}
+/** Reaction level resolution result */
+export interface ReactionLevelResult {
+    level: "off" | "ack" | "minimal" | "extensive";
+    agentReactionsEnabled: boolean;
+}
+//# sourceMappingURL=config-types.d.ts.map

package/dist/gateway/channels/telegram/config-types.js

@@ -0,0 +1 @@
+export{};

package/dist/gateway/channels/telegram/edit-delete.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Telegram edit and delete module
+ *
+ * Provides message editing and deletion functionality.
+ */
+import type { TelegramEditOptions, TelegramEditResult, TelegramDeleteResult, TelegramRetryConfig } from "./config-types.js";
+/**
+ * Edit a Telegram message.
+ *
+ * Features:
+ * - HTML parse fallback to plain text
+ * - Button removal support (pass empty array)
+ * - MESSAGE_NOT_MODIFIED error suppression (treated as success)
+ * - Retry policy integration
+ *
+ * @param chatId Chat ID where the message is located
+ * @param messageId Message ID to edit
+ * @param text New message text (markdown format)
+ * @param token Bot token
+ * @param opts Edit options (buttons, linkPreview, retry)
+ * @returns Edit result with message ID and chat ID
+ *
+ * @example
+ * ```ts
+ * // Edit text
+ * await editMessageTelegram(
+ *   "123456",
+ *   42,
+ *   "Updated text",
+ *   "bot-token",
+ * );
+ *
+ * // Edit with buttons
+ * await editMessageTelegram(
+ *   "123456",
+ *   42,
+ *   "Choose:",
+ *   "bot-token",
+ *   {
+ *     buttons: [[
+ *       { text: "Yes", callback_data: "yes" },
+ *       { text: "No", callback_data: "no" },
+ *     ]],
+ *   },
+ * );
+ *
+ * // Remove buttons
+ * await editMessageTelegram(
+ *   "123456",
+ *   42,
+ *   "Text without buttons",
+ *   "bot-token",
+ *   { buttons: [] },
+ * );
+ * ```
+ */
+export declare function editMessageTelegram(chatId: string | number, messageId: string | number, text: string, token: string, opts?: TelegramEditOptions): Promise<TelegramEditResult>;
+/**
+ * Delete a Telegram message.
+ *
+ * @param chatId Chat ID where the message is located
+ * @param messageId Message ID to delete
+ * @param token Bot token
+ * @param retry Optional retry configuration
+ * @returns Delete result
+ *
+ * @example
+ * ```ts
+ * await deleteMessageTelegram("123456", 42, "bot-token");
+ * ```
+ */
+export declare function deleteMessageTelegram(chatId: string | number, messageId: string | number, token: string, retry?: TelegramRetryConfig): Promise<TelegramDeleteResult>;
+//# sourceMappingURL=edit-delete.d.ts.map

package/dist/gateway/channels/telegram/edit-delete.js

@@ -0,0 +1 @@
+import{Bot as e}from"grammy";import{createLogger as t}from"../../../utils/logger.js";import{normalizeChatId as r,normalizeMessageId as i}from"./utils.js";import{buildInlineKeyboard as s}from"./inline-buttons.js";import{createRetryRunner as o}from"./retry-policy.js";import{withHtmlParseFallback as a,isTelegramMessageNotModifiedError as n}from"./error-handling.js";const d=t("telegram:edit");export async function editMessageTelegram(t,g,l,p,c={}){if(!p)throw new Error("Telegram bot token is required");const m=r(String(t)),u=i(g),b=new e(p).api,_=o(void 0,!1),f=function(e){let t=e;return t=t.replace(/```([\s\S]*?)```/g,"<pre><code>$1</code></pre>"),t=t.replace(/`([^`]+)`/g,"<code>$1</code>"),t=t.replace(/\*\*([^*]+)\*\*/g,"<b>$1</b>"),t=t.replace(/\*([^*]+)\*/g,"<i>$1</i>"),t=t.replace(/__([^_]+)__/g,"<u>$1</u>"),t=t.replace(/~~([^~]+)~~/g,"<s>$1</s>"),t}(l),w=void 0!==c.buttons,k=w?s(c.buttons):void 0,M=w?k??{inline_keyboard:[]}:void 0,$={parse_mode:"HTML"};!1===c.linkPreview&&($.link_preview_options={is_disabled:!0}),void 0!==M&&($.reply_markup=M);const h={};!1===c.linkPreview&&(h.link_preview_options={is_disabled:!0}),void 0!==M&&(h.reply_markup=M);try{await a({label:"editMessage",requestHtml:()=>_(()=>b.editMessageText(m,u,f,$),"editMessage"),requestPlain:()=>_(()=>Object.keys(h).length>0?b.editMessageText(m,u,l,h):b.editMessageText(m,u,l),"editMessage-plain")})}catch(e){if(!n(e))throw e;d.debug(`Message ${u} not modified (content unchanged)`)}return d.debug(`Edited message ${u} in chat ${m}`),{ok:!0,messageId:String(u),chatId:m}}export async function deleteMessageTelegram(t,s,a,n){if(!a)throw new Error("Telegram bot token is required");const g=r(String(t)),l=i(s),p=new e(a).api,c=o(n,!1);return await c(()=>p.deleteMessage(g,l),"deleteMessage"),d.debug(`Deleted message ${l} from chat ${g}`),{ok:!0}}

package/dist/gateway/channels/telegram/error-handling.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Telegram error handling utilities
+ *
+ * This module provides error handling patterns for Telegram API calls:
+ * - HTML parse error fallback (retry as plain text)
+ * - Thread not found fallback (retry without thread ID)
+ * - Chat not found error enrichment
+ */
+/**
+ * Check if error is a Telegram message not modified error.
+ */
+export declare function isTelegramMessageNotModifiedError(err: unknown): boolean;
+/**
+ * Wrap a Telegram API call with HTML parse error fallback.
+ *
+ * If the request fails with an HTML parse error, it retries with plain text.
+ *
+ * @example
+ * ```ts
+ * const result = await withHtmlParseFallback({
+ *   label: "sendMessage",
+ *   requestHtml: () => api.sendMessage(chatId, text, { parse_mode: "HTML" }),
+ *   requestPlain: () => api.sendMessage(chatId, text),
+ * });
+ * ```
+ */
+export declare function withHtmlParseFallback<T>(params: {
+    label: string;
+    requestHtml: () => Promise<T>;
+    requestPlain: () => Promise<T>;
+}): Promise<T>;
+/**
+ * Wrap a Telegram API call with thread fallback.
+ *
+ * If the request fails with "message thread not found", it retries without the
+ * message_thread_id parameter.
+ *
+ * @example
+ * ```ts
+ * const result = await withThreadFallback(
+ *   { message_thread_id: 123, text: "Hello" },
+ *   "sendMessage",
+ *   async (effectiveParams) => api.sendMessage(chatId, effectiveParams),
+ * );
+ * ```
+ */
+export declare function withThreadFallback<T>(params: Record<string, unknown> | undefined, label: string, attempt: (effectiveParams: Record<string, unknown> | undefined) => Promise<T>): Promise<T>;
+/**
+ * Wrap a chat not found error with enhanced context.
+ *
+ * Enriches the error message with helpful troubleshooting information.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await api.sendMessage(chatId, "Hello");
+ * } catch (err) {
+ *   throw wrapChatNotFoundError(err, chatId, "message text");
+ * }
+ * ```
+ */
+export declare function wrapChatNotFoundError(err: unknown, chatId: string, input: string): Error;
+//# sourceMappingURL=error-handling.d.ts.map

package/dist/gateway/channels/telegram/error-handling.js

@@ -0,0 +1 @@
+import{createLogger as t}from"../../../utils/logger.js";const e=t("telegram:errors"),r=/can't parse entities|parse entities|find end of the entity/i,n=/400:\s*Bad Request:\s*message thread not found/i,i=/400:\s*Bad Request:\s*message is not modified|MESSAGE_NOT_MODIFIED/i,a=/400: Bad Request: chat not found/i;function o(t){return t instanceof Error?t.message:String(t)}export function isTelegramMessageNotModifiedError(t){return i.test(o(t))}function s(t){return null!=t&&"message_thread_id"in t}export async function withHtmlParseFallback(t){try{return await t.requestHtml()}catch(n){if(!function(t){return r.test(o(t))}(n))throw n;return e.warn(`Telegram ${t.label} failed with HTML parse error, retrying as plain text: ${o(n)}`),await t.requestPlain()}}export async function withThreadFallback(t,r,i){try{return await i(t)}catch(a){if(!s(t)||!function(t){return n.test(o(t))}(a))throw a;e.warn(`Telegram ${r} failed with message_thread_id, retrying without thread: ${o(a)}`);const u=function(t){if(!t||!s(t))return t;const e={...t};return delete e.message_thread_id,Object.keys(e).length>0?e:void 0}(t);return await i(u)}}export function wrapChatNotFoundError(t,e,r){return function(t){return a.test(o(t))}(t)?new Error([`Telegram send failed: chat not found (chat_id=${e}).`,"Likely: bot not started in DM, bot removed from group/channel, group migrated (new -100… id), or wrong bot token.",`Input was: ${JSON.stringify(r)}.`].join(" ")):t instanceof Error?t:new Error(String(t))}

package/dist/gateway/channels/{telegram.d.ts → telegram/index.d.ts}

@@ -1,19 +1,28 @@
-import type { ChannelAdapter, MessageHandler, InlineButton } from "../bridge.js";
-import type { TokenDB } from "../../auth/token-db.js";
-interface TelegramAccountConfig {
-    botToken: string;
-    dmPolicy: string;
-    allowFrom: Array<string | number>;
-}
+/**
+ * Telegram Channel Adapter
+ *
+ * Modular Telegram channel implementation with advanced features:
+ * - Message reactions
+ * - Edit and delete messages
+ * - Sticker cache with fuzzy search
+ * - Forum topic & thread support
+ * - Inline button scope control
+ * - Advanced retry policy
+ * - Poll creation
+ */
+import type { ChannelAdapter, MessageHandler, InlineButton } from "../../bridge.js";
+import type { TokenDB } from "../../../auth/token-db.js";
+import type { TelegramAccountConfig } from "../../../config.js";
 export declare class TelegramChannel implements ChannelAdapter {
     readonly name = "telegram";
     private bot;
     private config;
+    private accountId;
     private tokenDb;
     private typingIntervals;
     private inflightTyping;
     private inflightCount;
-    constructor(config: TelegramAccountConfig, tokenDb: TokenDB, inflightTyping?: boolean);
+    constructor(config: TelegramAccountConfig, accountId: string, tokenDb: TokenDB, inflightTyping?: boolean);
     start(onMessage: MessageHandler): Promise<void>;
     sendText(chatId: string, text: string): Promise<void>;
     setTyping(chatId: string): Promise<void>;
@@ -23,8 +32,12 @@ export declare class TelegramChannel implements ChannelAdapter {
     releaseTyping(chatId: string): Promise<void>;
     private startTypingInterval;
     private stopTypingInterval;
-    sendButtons(chatId: string, text: string, buttons: InlineButton[]): Promise<void>;
+    sendButtons(chatId: string, text: string, buttons: InlineButton[][]): Promise<void>;
     sendAudio(chatId: string, filePath: string, asVoice?: boolean): Promise<void>;
+    reactMessage(chatId: string, messageId: string, emoji: string, remove?: boolean): Promise<void>;
+    editMessage(chatId: string, messageId: string, text: string, buttons?: InlineButton[]): Promise<void>;
+    deleteMessage(chatId: string, messageId: string): Promise<void>;
+    sendSticker(chatId: string, fileId: string): Promise<void>;
     stop(): Promise<void>;
     /**
      * Process an incoming message in the background.
@@ -35,5 +48,4 @@ export declare class TelegramChannel implements ChannelAdapter {
     private downloadFile;
     private sendChunked;
 }
-export {};
-//# sourceMappingURL=telegram.d.ts.map
+//# sourceMappingURL=index.d.ts.map

package/dist/gateway/channels/telegram/index.js

@@ -0,0 +1 @@
+import{Bot as t,InputFile as e}from"grammy";import{validateChannelUser as i}from"../../../auth/auth-middleware.js";import{parseMediaLines as n}from"../../../utils/media-response.js";import{markdownToTelegramHtmlChunks as a}from"../../../utils/telegram-format.js";import{createLogger as o}from"../../../utils/logger.js";import{sendMessageTelegram as s}from"./send.js";import{reactMessageTelegram as r,resolveReactionLevel as c}from"./reactions.js";import{editMessageTelegram as l,deleteMessageTelegram as d}from"./edit-delete.js";import{sendStickerTelegram as h,cacheSticker as g}from"./stickers.js";import{validateButtonsForChatId as m}from"./inline-buttons.js";const f=o("Telegram");export class TelegramChannel{name="telegram";bot;config;accountId;tokenDb;typingIntervals=new Map;inflightTyping;inflightCount=new Map;constructor(e,i,n,a=!0){this.config=e,this.accountId=i,this.tokenDb=n,this.inflightTyping=a,this.bot=new t(e.botToken)}async start(t){this.bot.on("message",e=>{this.handleIncoming(e,t)}),this.bot.on("callback_query:data",e=>{const i=e.callbackQuery.data,n=String(e.from?.id??"unknown"),a=String(e.chat?.id??e.callbackQuery.message?.chat?.id??"unknown"),o=e.from?.username;e.answerCallbackQuery().catch(()=>{}),this.startTypingInterval(a);t({chatId:a,userId:n,channelName:"telegram",text:i,attachments:[],username:o,rawContext:e}).then(async t=>{t&&t.trim()&&await this.sendText(a,t)}).catch(t=>{f.error(`Error handling callback from ${n}: ${t}`)})}),f.info("Starting Telegram bot..."),this.bot.start({onStart:t=>{f.info(`Telegram bot started: @${t.username}`)}}).catch(t=>{String(t).includes("Aborted delay")?f.debug("Telegram polling stopped"):f.error(`Telegram bot polling error: ${t}`)})}async sendText(t,e){try{await s(t,e,{token:this.config.botToken,accountId:this.accountId,textChunkLimit:this.config.textChunkLimit,linkPreview:this.config.linkPreview,retry:this.config.retry})}catch(t){throw f.error(`Failed to send message: ${t}`),t}await this.resendTypingIfActive(t)}async setTyping(t){this.typingIntervals.has(t)?await this.bot.api.sendChatAction(t,"typing").catch(()=>{}):this.startTypingInterval(t)}async resendTypingIfActive(t){this.typingIntervals.has(t)&&await this.bot.api.sendChatAction(t,"typing").catch(()=>{})}async clearTyping(t){this.inflightCount.delete(t);const e=this.typingIntervals.get(t);e&&(clearInterval(e),this.typingIntervals.delete(t))}async releaseTyping(t){this.stopTypingInterval(t)}startTypingInterval(t){if(this.inflightTyping){const e=(this.inflightCount.get(t)??0)+1;if(this.inflightCount.set(t,e),e>1)return}const e=this.typingIntervals.get(t);e&&(clearInterval(e),this.typingIntervals.delete(t)),this.bot.api.sendChatAction(t,"typing").catch(()=>{});const i=setInterval(()=>{const e=this.inflightCount.get(t)??0;!this.inflightTyping||e>0?this.bot.api.sendChatAction(t,"typing").catch(()=>{}):(clearInterval(i),this.typingIntervals.delete(t))},4e3);this.typingIntervals.set(t,i)}stopTypingInterval(t){if(this.inflightTyping){const e=(this.inflightCount.get(t)??1)-1;return void(e>0?this.inflightCount.set(t,e):this.inflightCount.delete(t))}const e=this.typingIntervals.get(t);e&&(clearInterval(e),this.typingIntervals.delete(t))}async sendButtons(t,e,i){const n=i.map(t=>t.map(t=>({text:t.text,callback_data:t.callbackData??t.text})));try{m(n,this.config,t)}catch(i){return f.warn(`Button validation failed: ${i}, sending without buttons`),void await this.sendText(t,e)}await s(t,e,{token:this.config.botToken,accountId:this.accountId,buttons:n,textChunkLimit:this.config.textChunkLimit,linkPreview:this.config.linkPreview,retry:this.config.retry}),await this.resendTypingIfActive(t)}async sendAudio(t,i,n){const a=new e(i);n?await this.bot.api.sendVoice(t,a):await this.bot.api.sendAudio(t,a),await this.resendTypingIfActive(t)}async reactMessage(t,e,i,n){const{level:a}=c(this.config);"off"!==a?await r(t,e,i,this.config.botToken,{remove:n}):f.debug("Reactions disabled for this account")}async editMessage(t,e,i,n){const a=n?.map(t=>({text:t.text,callback_data:t.callbackData??t.text}));await l(t,e,i,this.config.botToken,{buttons:a?[a]:void 0,linkPreview:this.config.linkPreview})}async deleteMessage(t,e){await d(t,e,this.config.botToken,this.config.retry)}async sendSticker(t,e){await h(t,e,this.config.botToken,{retry:this.config.retry}),await this.resendTypingIfActive(t)}async stop(){try{await this.bot.stop(),f.info("Telegram bot stopped"),await new Promise(t=>setTimeout(t,100))}catch(t){f.warn(`Error stopping Telegram bot: ${t}`)}}async handleIncoming(t,a){const o=String(t.from?.id??"unknown"),s=String(t.chat?.id??"unknown"),r=t.from?.username,c=i(this.tokenDb,o,"telegram",this.config.dmPolicy,this.config.allowFrom);if(!c.authorized)return f.warn(`Unauthorized message from ${o} (@${r})`),void await t.reply(c.reason??"Not authorized.");this.startTypingInterval(s);try{const i=await this.buildIncomingMessage(t,s,o,r),c=await a(i),{textParts:l,mediaEntries:d}=n(c);for(const i of d)try{const n=new e(i.path);i.asVoice?await t.replyWithVoice(n):await t.replyWithAudio(n)}catch(t){f.error(`Failed to send audio: ${t}`)}const h=l.join("\n").trim();h&&await this.sendChunked(t,h),await this.resendTypingIfActive(s)}catch(e){f.error(`Error handling message from ${o}: ${e}`),await t.reply("An error occurred while processing your message.").catch(()=>{})}}async buildIncomingMessage(t,e,i,n){const a=t.message,o=[];let s=a.text??a.caption??void 0;if(a.photo&&a.photo.length>0){const e=a.photo[a.photo.length-1];o.push({type:"image",mimeType:"image/jpeg",fileSize:e.file_size,caption:a.caption,getBuffer:()=>this.downloadFile(t,e.file_id)})}if(a.voice&&o.push({type:"voice",mimeType:a.voice.mime_type??"audio/ogg",duration:a.voice.duration,fileSize:a.voice.file_size,getBuffer:()=>this.downloadFile(t,a.voice.file_id)}),a.audio&&o.push({type:"audio",mimeType:a.audio.mime_type??"audio/mpeg",fileName:a.audio.file_name,duration:a.audio.duration,fileSize:a.audio.file_size,caption:a.caption,getBuffer:()=>this.downloadFile(t,a.audio.file_id)}),a.document&&o.push({type:"document",mimeType:a.document.mime_type,fileName:a.document.file_name,fileSize:a.document.file_size,caption:a.caption,getBuffer:()=>this.downloadFile(t,a.document.file_id)}),a.video&&o.push({type:"video",mimeType:a.video.mime_type??"video/mp4",fileName:a.video.file_name,duration:a.video.duration,fileSize:a.video.file_size,caption:a.caption,getBuffer:()=>this.downloadFile(t,a.video.file_id)}),a.video_note&&o.push({type:"video_note",mimeType:"video/mp4",duration:a.video_note.duration,fileSize:a.video_note.file_size,getBuffer:()=>this.downloadFile(t,a.video_note.file_id)}),a.sticker){if(this.config.actions?.sticker)try{g({fileId:a.sticker.file_id,fileUniqueId:a.sticker.file_unique_id,emoji:a.sticker.emoji,setName:a.sticker.set_name,description:a.sticker.emoji?`${a.sticker.emoji} sticker${a.sticker.set_name?` from ${a.sticker.set_name}`:""}`:a.sticker.set_name??"sticker"})}catch(t){f.warn(`Failed to cache sticker: ${t}`)}o.push({type:"sticker",mimeType:a.sticker.is_animated?"application/x-tgsticker":a.sticker.is_video?"video/webm":"image/webp",metadata:{emoji:a.sticker.emoji,setName:a.sticker.set_name},getBuffer:()=>this.downloadFile(t,a.sticker.file_id)})}return a.location&&o.push({type:"location",metadata:{latitude:a.location.latitude,longitude:a.location.longitude},getBuffer:async()=>Buffer.alloc(0)}),a.contact&&o.push({type:"contact",metadata:{phoneNumber:a.contact.phone_number,firstName:a.contact.first_name,lastName:a.contact.last_name,userId:a.contact.user_id},getBuffer:async()=>Buffer.alloc(0)}),{chatId:e,userId:i,channelName:"telegram",text:s,attachments:o,username:n,rawContext:t}}async downloadFile(t,e){const i=await t.api.getFile(e),n=`https://api.telegram.org/file/bot${this.config.botToken}/${i.file_path}`,a=await fetch(n);if(!a.ok)throw new Error(`Failed to download file: ${a.statusText}`);return Buffer.from(await a.arrayBuffer())}async sendChunked(t,e){const i=a(e,4096);for(const n of i)try{await t.reply(n,{parse_mode:"HTML"})}catch{const i=p(e,4096);for(const e of i)await t.reply(e);break}}}function p(t,e){if(t.length<=e)return[t];const i=[];let n=t;for(;n.length>0;){if(n.length<=e){i.push(n);break}let t=n.lastIndexOf("\n",e);t<=0&&(t=e),i.push(n.slice(0,t)),n=n.slice(t).trimStart()}return i}

package/dist/gateway/channels/telegram/inline-buttons.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Telegram inline buttons utilities
+ *
+ * This module provides inline button scope validation and keyboard rendering
+ * for Telegram's reply_markup system.
+ */
+import type { InlineKeyboardMarkup } from "@grammyjs/types";
+import type { TelegramAccountConfig, TelegramChatType, TelegramInlineButtonsScope, TelegramInlineButtons } from "./config-types.js";
+/**
+ * Resolve inline buttons scope from account configuration.
+ *
+ * The scope determines where inline buttons are allowed:
+ * - "off": Buttons disabled everywhere
+ * - "dm": Buttons only in direct messages
+ * - "group": Buttons only in groups
+ * - "all": Buttons allowed everywhere
+ * - "allowlist": Buttons allowed based on allowlist (default)
+ */
+export declare function resolveInlineButtonsScope(config: TelegramAccountConfig): TelegramInlineButtonsScope;
+/**
+ * Validate that buttons are allowed for the given scope and chat type.
+ *
+ * Throws an error if buttons are not allowed in this context.
+ *
+ * @throws {Error} If buttons are used in an invalid context
+ */
+export declare function validateButtonsForScope(buttons: TelegramInlineButtons | undefined, scope: TelegramInlineButtonsScope, chatType: TelegramChatType): void;
+/**
+ * Build Telegram InlineKeyboardMarkup from button array.
+ *
+ * Takes an array of button rows (TelegramInlineButtons[][]).
+ *
+ * Filters out invalid buttons (missing text or callback_data).
+ * Returns undefined if no valid buttons remain.
+ *
+ * @example
+ * ```ts
+ * // Single row
+ * const markup = buildInlineKeyboard([
+ *   [
+ *     { text: "Yes", callback_data: "yes" },
+ *     { text: "No", callback_data: "no" },
+ *   ]
+ * ]);
+ *
+ * // Multiple rows
+ * const markup = buildInlineKeyboard([
+ *   [{ text: "Option 1", callback_data: "opt1" }],
+ *   [{ text: "Option 2", callback_data: "opt2" }],
+ * ]);
+ * ```
+ */
+export declare function buildInlineKeyboard(buttons?: TelegramInlineButtons): InlineKeyboardMarkup | undefined;
+/**
+ * Convenience wrapper to resolve chat type and validate buttons.
+ *
+ * @throws {Error} If buttons are not allowed in this context
+ */
+export declare function validateButtonsForChatId(buttons: TelegramInlineButtons | undefined, config: TelegramAccountConfig, chatId: string): void;
+//# sourceMappingURL=inline-buttons.d.ts.map

package/dist/gateway/channels/telegram/inline-buttons.js

@@ -0,0 +1 @@
+import{resolveChatType as t}from"./utils.js";export function resolveInlineButtonsScope(t){return t.inlineButtonsScope??"allowlist"}export function validateButtonsForScope(t,e,o){if(t&&0!==t.length){if("off"===e)throw new Error("Inline buttons are disabled for this Telegram account (scope: off)");if("dm"===e&&"direct"!==o)throw new Error(`Inline buttons are only allowed in direct messages for this account (scope: dm, chatType: ${o})`);if("group"===e&&"group"!==o)throw new Error(`Inline buttons are only allowed in groups for this account (scope: group, chatType: ${o})`)}}export function buildInlineKeyboard(t){if(!t||0===t.length)return;const e=t.map(t=>t.filter(t=>t?.text&&t?.callback_data).map(t=>{!function(t,e){if(t.length>64)throw new Error(`Telegram callback_data exceeds 64 characters (button: "${e}", length: ${t.length})`)}(t.callback_data,t.text);return{text:t.text,callback_data:t.callback_data}})).filter(t=>t.length>0);return 0!==e.length?{inline_keyboard:e}:void 0}export function validateButtonsForChatId(e,o,n){validateButtonsForScope(e,resolveInlineButtonsScope(o),t(n))}

package/dist/gateway/channels/telegram/polls.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Telegram polls module
+ *
+ * Provides poll creation functionality with validation.
+ */
+import type { TelegramPollOptions, TelegramPollSendResult, TelegramRetryConfig } from "./config-types.js";
+/**
+ * Send a poll to a Telegram chat.
+ *
+ * Features:
+ * - Poll validation (2-10 options, 5-600s duration)
+ * - Multi-select support
+ * - Thread support (forum topics, reply-to)
+ * - Anonymous/public polls
+ * - Retry policy integration
+ *
+ * @param to Target chat ID (with optional thread: "chatId:topic:topicId")
+ * @param poll Poll configuration (question, options, maxSelections, duration, anonymous)
+ * @param token Bot token
+ * @param retry Optional retry configuration
+ * @returns Poll send result with message ID, chat ID, and optional poll ID
+ *
+ * @example
+ * ```ts
+ * // Simple poll
+ * await sendPollTelegram(
+ *   "123456",
+ *   {
+ *     question: "What's your favorite color?",
+ *     options: ["Red", "Blue", "Green"],
+ *   },
+ *   "bot-token",
+ * );
+ *
+ * // Multi-select poll with duration
+ * await sendPollTelegram(
+ *   "123456",
+ *   {
+ *     question: "Which features do you want?",
+ *     options: ["Feature A", "Feature B", "Feature C"],
+ *     maxSelections: 3,
+ *     durationSeconds: 300,
+ *     isAnonymous: false,
+ *   },
+ *   "bot-token",
+ * );
+ * ```
+ */
+export declare function sendPollTelegram(to: string, poll: TelegramPollOptions, token: string, retry?: TelegramRetryConfig): Promise<TelegramPollSendResult>;
+//# sourceMappingURL=polls.d.ts.map

package/dist/gateway/channels/telegram/polls.js

@@ -0,0 +1 @@
+import{Bot as o}from"grammy";import{createLogger as e}from"../../../utils/logger.js";import{parseTelegramTarget as t,normalizeChatId as r}from"./utils.js";import{buildThreadReplyParams as n}from"./thread-support.js";import{createRetryRunner as s}from"./retry-policy.js";import{withThreadFallback as i,wrapChatNotFoundError as l}from"./error-handling.js";const a=e("telegram:polls");export async function sendPollTelegram(e,d,m,h){if(!m)throw new Error("Telegram bot token is required");!function(o){if(!o.question||0===o.question.trim().length)throw new Error("Poll question cannot be empty");if(o.question.length>300)throw new Error("Poll question must be 300 characters or less");if(!Array.isArray(o.options)||o.options.length<2)throw new Error("Poll must have at least 2 options");if(o.options.length>10)throw new Error("Poll can have at most 10 options");for(const e of o.options){if(!e||0===e.trim().length)throw new Error("Poll option cannot be empty");if(e.length>100)throw new Error("Poll option must be 100 characters or less")}const e=o.maxSelections??1;if(e<1||e>o.options.length)throw new Error(`Poll maxSelections must be between 1 and ${o.options.length}`);if(void 0!==o.durationSeconds&&(o.durationSeconds<5||o.durationSeconds>600))throw new Error("Poll duration must be between 5 and 600 seconds")}(d);const p=t(e),c=r(p.chatId),u=new o(m).api,g=s(h,!1),w=n({targetMessageThreadId:p.messageThreadId,messageThreadId:d.messageThreadId,chatType:p.chatType,replyToMessageId:d.replyToMessageId}),f={allows_multiple_answers:(d.maxSelections??1)>1,is_anonymous:d.isAnonymous??!0,...void 0!==d.durationSeconds?{open_period:d.durationSeconds}:{},...w},y=async(o,t)=>{try{return await g(o,t)}catch(o){throw l(o,c,e)}};let P;P=Object.keys(w).length>0?await i(f,"sendPoll",o=>y(()=>u.sendPoll(c,d.question,d.options,o||{}),"sendPoll")):await y(()=>u.sendPoll(c,d.question,d.options,f),"sendPoll");const b=String(P.message_id),S=String(P.chat.id),I=P.poll?.id;return a.debug(`Sent poll to chat ${S}, message ${b}`),{messageId:b,chatId:S,pollId:I}}