@c4t4/heyamigo 0.9.16 → 0.9.18

package/dist/ai/claude.js

@@ -202,6 +202,9 @@ export async function runClaudeTask(params) {
 }
 export const claudeProvider = {
     name: 'claude',
+    // Claude CLI's `result` event reports per-turn usage (just the
+    // tokens consumed by this single resume invocation).
+    usageReportingMode: 'per-turn',
     ask: askClaude,
     runTask: runClaudeTask,
     reloadSystemPrompt,

package/dist/ai/codex.js

@@ -267,6 +267,11 @@ async function askCodex(params) {
 }
 export const codexProvider = {
     name: 'codex',
+    // Codex CLI's `turn.completed.usage` reports cumulative totals for
+    // the entire resume thread, not just this one turn. Worker uses
+    // this flag to delta-math each turn before display so the context
+    // % doesn't blow up to thousands after many resume turns.
+    usageReportingMode: 'cumulative',
     ask: askCodex,
     runTask: runCodexTask,
     reloadSystemPrompt,

package/dist/db/schema.js

@@ -159,6 +159,12 @@ export const inbound = sqliteTable('inbound', {
     mediaBytes: integer('media_bytes'),
     pushName: text('push_name'), // sender's display name at send time
     triggerReason: text('trigger_reason'), // 'alias'|'mention'|'reply'|'owner'|...
+    // Job-kind tag for duration estimation (see src/estimates/). Set
+    // at ingest time when a registered estimator matches the message
+    // (e.g. 'image-gen', 'browser:ig'). Null otherwise. Queried by
+    // the estimator on subsequent invocations to compute past-sample
+    // averages.
+    kind: text('kind'),
     // Producer-built worker payload (JSON). Chat worker deserializes
     // at claim time to reconstruct the Job. Keeps the rebuild logic
     // out of the worker for Phase 4; later phases may move portions
@@ -179,6 +185,8 @@ export const inbound = sqliteTable('inbound', {
     byStatusNext: index('inbound_by_status_next').on(t.status, t.nextAttemptAt),
     byAddress: index('inbound_by_address').on(t.address),
     byPerson: index('inbound_by_person').on(t.personId, t.receivedAt),
+    // Used by the duration estimator: "last N done rows of this kind".
+    byKindDone: index('inbound_by_kind_done').on(t.kind, t.status),
     // Sparse unique on external_msg_id: enforced only when set. Same
     // pattern as outbound's idempotency_key.
     uniqExtId: uniqueIndex('inbound_external_msg_id_uq')

package/dist/estimates/image-gen.js

@@ -0,0 +1,36 @@
+// Image-generation estimator. Matches when the user message looks
+// like a request to produce an image. Tracks duration of the chat-
+// track turn that handles it (claimedAt → updatedAt on the inbound
+// row).
+import { aggregateMean, registerEstimator } from './registry.js';
+// Conservative regex. Requires a generation verb AND an image-class
+// noun within 80 chars. Prefers false-negative to false-positive —
+// a single mistagged sample drags the average for everyone.
+const IMAGE_GEN_RE = /\b(generate|create|make|draw|render|design|sketch|paint|illustrate)\b[^.?!\n]{0,80}\b(image|picture|drawing|art|artwork|photo|portrait|illustration|sketch|render|painting|wallpaper|logo|icon|graphic)\b/i;
+class ImageGenEstimator {
+    kind = 'image-gen';
+    // 30s starting point — reasonable ballpark for current
+    // image-generation APIs (DALL-E 3, Imagen, Flux, etc.). The very
+    // first request shows this; from sample 1 onward it averages real
+    // observations.
+    defaultMs = 30_000;
+    matches(ctx) {
+        return IMAGE_GEN_RE.test(ctx.description);
+    }
+    estimate(samples) {
+        return aggregateMean(samples, this.defaultMs);
+    }
+    format(estimate) {
+        if (estimate.rangeMs) {
+            return `generating image, anywhere from ~${secs(estimate.rangeMs.lowMs)} to ~${secs(estimate.rangeMs.highMs)}`;
+        }
+        return `generating image, ~${secs(estimate.pointMs)}`;
+    }
+}
+function secs(ms) {
+    const s = Math.max(1, Math.round(ms / 1000));
+    if (s < 60)
+        return `${s}s`;
+    return `${Math.round(s / 60)}min`;
+}
+registerEstimator(new ImageGenEstimator());

package/dist/estimates/index.js

@@ -0,0 +1,12 @@
+// Estimates module entry point. Importing this side-effect-loads
+// every built-in plugin (each plugin file calls registerEstimator()
+// at module load). Outside callers only need:
+//
+//   import { classify, estimate } from './estimates/index.js'
+//
+// Adding a new kind = drop a file alongside image-gen.ts and import
+// it below. No other code in the codebase needs to change.
+import './image-gen.js';
+// future: import './browser-ig.js'
+// future: import './voice-gen.js'
+export { classify, estimate, formatEstimateDefault, humanDur, listEstimators, querySamplesForKind, registerEstimator, } from './registry.js';

package/dist/estimates/registry.js

@@ -0,0 +1,113 @@
+// Estimator registry + the single entry points the rest of the bot
+// uses: classify() and estimate(). Plugins self-register by importing
+// this module and calling registerEstimator().
+import { and, desc, eq, isNotNull } from 'drizzle-orm';
+import { getDb } from '../db/index.js';
+import { inbound } from '../db/schema.js';
+const REGISTRY = [];
+export function registerEstimator(e) {
+    // Idempotent on kind so hot-reload during dev doesn't duplicate.
+    const i = REGISTRY.findIndex((x) => x.kind === e.kind);
+    if (i >= 0)
+        REGISTRY[i] = e;
+    else
+        REGISTRY.push(e);
+}
+export function listEstimators() {
+    return REGISTRY;
+}
+// Find the first estimator whose matches() returns true. First-match
+// wins — order matters when registering. More-specific kinds should
+// register before broad fallbacks.
+export function classify(ctx) {
+    for (const e of REGISTRY) {
+        if (e.matches(ctx))
+            return e;
+    }
+    return null;
+}
+// Pull the last N completed inbound rows for this kind. Returns
+// newest-first; estimators that care about recency can use that
+// order directly, the mean-based aggregator below doesn't.
+//
+// Limited to N=20 by default. The mean is fast and stable past 5-10
+// samples; older data isn't helpful and risks staleness.
+const SAMPLE_LIMIT = 20;
+export function querySamplesForKind(kind, limit = SAMPLE_LIMIT) {
+    const db = getDb();
+    const rows = db
+        .select({
+        claimedAt: inbound.claimedAt,
+        updatedAt: inbound.updatedAt,
+    })
+        .from(inbound)
+        .where(and(eq(inbound.kind, kind), eq(inbound.status, 'done'), isNotNull(inbound.claimedAt)))
+        .orderBy(desc(inbound.id))
+        .limit(limit)
+        .all();
+    return rows
+        .filter((r) => r.claimedAt !== null)
+        .map((r) => ({
+        durationMs: (r.updatedAt - r.claimedAt) * 1000,
+        finishedAt: r.updatedAt,
+    }))
+        .filter((s) => s.durationMs > 0);
+}
+// Public entry point. Returns the kind + formatted text, or null
+// when no estimator matched (i.e. this isn't a job-kind we estimate).
+// If an estimator matches, the result is ALWAYS non-null — the
+// estimator falls back to its defaultMs when no samples exist.
+export function estimate(ctx) {
+    const e = classify(ctx);
+    if (!e)
+        return null;
+    const samples = querySamplesForKind(e.kind);
+    const result = e.estimate(samples);
+    const text = (e.format ?? formatEstimateDefault)(result);
+    return { kind: e.kind, result, text };
+}
+// Default UX-friendly rendering. Each estimator can override.
+export function formatEstimateDefault(r) {
+    if (r.rangeMs) {
+        return `anywhere from ~${humanDur(r.rangeMs.lowMs)} to ~${humanDur(r.rangeMs.highMs)}`;
+    }
+    return `~${humanDur(r.pointMs)}`;
+}
+export function humanDur(ms) {
+    const s = Math.max(1, Math.round(ms / 1000));
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.round(s / 60);
+    if (m < 60)
+        return `${m}min`;
+    return `${Math.round(m / 60)}h`;
+}
+// Shared aggregator used by built-in estimators. Each estimator may
+// implement its own estimate() but most just call this.
+export function aggregateMean(samples, defaultMs) {
+    if (samples.length === 0) {
+        return { pointMs: defaultMs, sampleSize: 0, confidence: 'low' };
+    }
+    const ds = samples.map((s) => s.durationMs);
+    const mean = ds.reduce((a, b) => a + b, 0) / ds.length;
+    if (samples.length === 1) {
+        return { pointMs: mean, sampleSize: 1, confidence: 'low' };
+    }
+    const variance = ds.reduce((acc, x) => acc + (x - mean) ** 2, 0) / ds.length;
+    const std = Math.sqrt(variance);
+    const confidence = samples.length >= 10 ? 'high' : samples.length >= 5 ? 'medium' : 'low';
+    // Disclose range when stddev is a large fraction of the mean.
+    // Threshold chosen at 50% — beyond that, a single point estimate
+    // hides too much.
+    return std / mean > 0.5
+        ? {
+            pointMs: mean,
+            sampleSize: samples.length,
+            confidence,
+            rangeMs: {
+                lowMs: Math.max(0, mean - std),
+                highMs: mean + std,
+            },
+        }
+        : { pointMs: mean, sampleSize: samples.length, confidence };
+}

package/dist/estimates/types.js

@@ -0,0 +1,6 @@
+// Job duration estimation interface. The system stays "blackbox" by
+// design — outside callers only touch the registry's classify() /
+// estimate() functions. Each kind plugs in via a self-contained file
+// in src/estimates/<kind>.ts that calls registerEstimator() at module
+// load.
+export {};

package/dist/gateway/commands.js

@@ -34,8 +34,11 @@ export async function tryCommand(ctx) {
         if (info.usage) {
             const max = config.claude.contextWindow;
             const used = info.usage.totalContextTokens;
-            const leftPct = Math.max(0, 100 - (used / max) * 100).toFixed(1);
-            lines.push(`Context: ${used.toLocaleString()} / ${max.toLocaleString()} (${leftPct}% left)`);
+            // Clamp leftPct to [0, 100] so stale or inconsistent data
+            // doesn't surface a negative or >100 percentage.
+            const leftRatio = Math.max(0, Math.min(1, 1 - used / max));
+            const leftPct = (leftRatio * 100).toFixed(1);
+            lines.push(`Context: ${used.toLocaleString()} / ${max.toLocaleString()} (${leftPct}% left, last turn)`);
             lines.push(`Turns: ${info.usage.numTurns}`);
         }
         await sendText(ctx.sock, ctx.jid, lines.join('\n'), ctx.quoted);

package/dist/gateway/incoming.js

@@ -5,6 +5,7 @@ import { getSession } from '../ai/sessions.js';
 import { formatAddress, jidToAddress } from '../db/address.js';
 import { personIdForAddress } from '../db/identity-sync.js';
 import { config } from '../config.js';
+import { estimate as estimateJob } from '../estimates/index.js';
 import { logger } from '../logger.js';
 import { buildMemoryPreamble } from '../memory/preamble.js';
 import { enqueueInbound } from '../queue/inbound.js';
@@ -216,12 +217,30 @@ async function processMessages(messages, sock, ownerJid, isHistorySync = false)
             const actorPersonId = senderAddress
                 ? personIdForAddress(senderAddress)
                 : null;
-            // For media-bearing messages, send an immediate "looking…" ack
-            // via outbound so the user isn't left wondering whether the bot
-            // saw the image (typing indicator was dropped in Phase 4 —
-            // followup commit will reinstate via ChannelAdapter.sendTyping).
-            // The chat worker still processes the actual reply normally.
-            if (media && config.reply.ackOnMedia !== false) {
+            // Estimator: classify this message and, when a kind matches,
+            // (a) tag the inbound row so future estimates of the same kind
+            // get a fresh sample, and (b) send the estimate text as an
+            // immediate ack so the user sees a timeline before the agent
+            // even starts.
+            const est = estimateJob({
+                description: stored.text,
+                attachments: media ? [{ kind: media.mediaType }] : undefined,
+                senderPersonId: actorPersonId ?? undefined,
+            });
+            const jobKind = est?.kind ?? null;
+            if (est) {
+                enqueueOutbound({
+                    address: chatAddress,
+                    kind: 'text',
+                    text: est.text,
+                    idempotencyKey: `estimate-${msg.key.id}`,
+                });
+            }
+            else if (media && config.reply.ackOnMedia !== false) {
+                // Fallback media-ack when no estimator matched — keeps the
+                // pre-estimator behavior so image messages still get the
+                // "looking…" hint. A future MediaIncomingEstimator can replace
+                // this with a real average.
                 enqueueOutbound({
                     address: chatAddress,
                     kind: 'text',
@@ -238,6 +257,7 @@ async function processMessages(messages, sock, ownerJid, isHistorySync = false)
                 text: stored.text,
                 pushName: stored.pushName ?? null,
                 triggerReason,
+                kind: jobKind,
                 receivedAt: stored.timestamp,
                 payload: job,
             });

package/dist/gateway/outgoing.js

@@ -171,13 +171,21 @@ export function formatStatsFooter(stats) {
         ? ` (${compactTokens(stats.cacheReadTokens)} cached)`
         : '';
     parts.push(`${inStr}↑${cacheStr} ${outStr}↓`);
-    // Context % — only when worth calling out
+    // Context % — only when worth calling out. Skipped when pct is
+    // implausible (>120%) — usually means cumulative/per-turn token
+    // counts got crossed by a stale session. Better to show nothing
+    // than display "7018% ctx" and lose user trust.
     if (stats.contextWindow > 0) {
         const pct = Math.round((stats.totalContextTokens / stats.contextWindow) * 100);
-        if (pct >= 90)
+        if (pct > 120) {
+            // skip — data is stale or inconsistent
+        }
+        else if (pct >= 90) {
             parts.push(`⚠ ${pct}% ctx`);
-        else if (pct >= 70)
+        }
+        else if (pct >= 70) {
             parts.push(`${pct}% ctx`);
+        }
     }
     if (stats.fresh)
         parts.push('fresh');

package/dist/queue/inbound.js

@@ -37,6 +37,7 @@ export function enqueueInbound(input) {
         mediaBytes: input.mediaBytes ?? null,
         pushName: input.pushName ?? null,
         triggerReason: input.triggerReason ?? null,
+        kind: input.kind ?? null,
         payload: input.payload === undefined ? null : JSON.stringify(input.payload),
         status: 'pending',
         attempts: 0,

package/dist/queue/worker.js

@@ -1,5 +1,5 @@
 import { getProvider } from '../ai/providers.js';
-import { clearSession, setSession, setUsage } from '../ai/sessions.js';
+import { clearSession, getSessionInfo, setSession, setUsage, } from '../ai/sessions.js';
 import { config } from '../config.js';
 import { formatAddress, jidToAddress } from '../db/address.js';
 import { logger } from '../logger.js';
@@ -18,6 +18,9 @@ async function callClaude(job) {
     const startedAt = Date.now();
     const wasFresh = !job.sessionId;
     const provider = getProvider();
+    // Capture prior session usage BEFORE the ask call so we can compute
+    // per-turn deltas regardless of the provider's reporting mode.
+    const priorUsage = getSessionInfo(job.jid, provider.name)?.usage;
     const { reply, sessionId, usage } = await provider.ask({
         input: job.input,
         sessionId: job.sessionId,
@@ -27,20 +30,76 @@ async function callClaude(job) {
     if (!job.sessionId) {
         setSession(job.jid, provider.name, sessionId);
     }
-    const totalContextTokens = usage.inputTokens +
-        usage.cacheReadTokens +
-        usage.cacheCreationTokens +
-        usage.outputTokens;
+    // Reconcile per-turn vs cumulative reporting. See AiProvider
+    // .usageReportingMode for context. For cumulative providers (Codex),
+    // the reported usage = whole-thread totals; we subtract the prior
+    // cumulative to get this turn's cost. For per-turn providers
+    // (Claude), the reported usage IS this turn's cost; we sum into
+    // the running cumulative.
+    //
+    // Fallback baseline: if cumulative* fields aren't stored yet
+    // (first turn after this fix deploys), use the prior plain field
+    // values. That treats the existing buggy-cumulative storage as the
+    // baseline so the next delta is accurate.
+    const baseCumInput = priorUsage?.cumulativeInputTokens ?? priorUsage?.inputTokens ?? 0;
+    const baseCumCacheRead = priorUsage?.cumulativeCacheReadTokens ?? priorUsage?.cacheReadTokens ?? 0;
+    const baseCumCacheCreate = priorUsage?.cumulativeCacheCreationTokens ?? priorUsage?.cacheCreationTokens ?? 0;
+    const baseCumOutput = priorUsage?.cumulativeOutputTokens ?? priorUsage?.outputTokens ?? 0;
+    let turnInput;
+    let turnCacheRead;
+    let turnCacheCreate;
+    let turnOutput;
+    let newCumInput;
+    let newCumCacheRead;
+    let newCumCacheCreate;
+    let newCumOutput;
+    if (provider.usageReportingMode === 'cumulative') {
+        // Reported usage IS the cumulative total. Delta = current - prev.
+        // Math.max(0, …) protects against the rare case where the CLI's
+        // counter resets (e.g. fresh session that we still tracked) —
+        // never display negative deltas.
+        newCumInput = usage.inputTokens;
+        newCumCacheRead = usage.cacheReadTokens;
+        newCumCacheCreate = usage.cacheCreationTokens;
+        newCumOutput = usage.outputTokens;
+        turnInput = Math.max(0, newCumInput - baseCumInput);
+        turnCacheRead = Math.max(0, newCumCacheRead - baseCumCacheRead);
+        turnCacheCreate = Math.max(0, newCumCacheCreate - baseCumCacheCreate);
+        turnOutput = Math.max(0, newCumOutput - baseCumOutput);
+    }
+    else {
+        // Reported usage IS per-turn already. Accumulate into cumulative.
+        turnInput = usage.inputTokens;
+        turnCacheRead = usage.cacheReadTokens;
+        turnCacheCreate = usage.cacheCreationTokens;
+        turnOutput = usage.outputTokens;
+        newCumInput = baseCumInput + turnInput;
+        newCumCacheRead = baseCumCacheRead + turnCacheRead;
+        newCumCacheCreate = baseCumCacheCreate + turnCacheCreate;
+        newCumOutput = baseCumOutput + turnOutput;
+    }
+    // totalContextTokens is the PROMPT side (input + cache reads + cache
+    // creation). Output is response, not context. The old code included
+    // outputTokens here which was wrong.
+    const totalContextTokens = turnInput + turnCacheRead + turnCacheCreate;
     setUsage(job.jid, provider.name, {
-        ...usage,
+        inputTokens: turnInput,
+        cacheReadTokens: turnCacheRead,
+        cacheCreationTokens: turnCacheCreate,
+        outputTokens: turnOutput,
         totalContextTokens,
+        numTurns: usage.numTurns,
+        cumulativeInputTokens: newCumInput,
+        cumulativeCacheReadTokens: newCumCacheRead,
+        cumulativeCacheCreationTokens: newCumCacheCreate,
+        cumulativeOutputTokens: newCumOutput,
         updatedAt: Math.floor(Date.now() / 1000),
     });
     // Per-user daily token accounting. Owner sender is exempt by check at the
     // incoming gate, but we still bill so /usage reflects reality if added.
     // Cache-read tokens are excluded — they don't cost real budget.
     if (job.senderNumber) {
-        addDailyTokens(job.senderNumber, usage.inputTokens + usage.outputTokens);
+        addDailyTokens(job.senderNumber, turnInput + turnOutput);
     }
     const rawFlags = extractFlags(reply);
     const { clean, digest, journals, journalCreates, asyncTasks, asyncBrowserTasks, sendTexts, crons, reminds, } = filterFlagsByRole(rawFlags, job.allowedTags);
@@ -179,9 +238,11 @@ async function callClaude(job) {
         reply: clean,
         stats: {
             durationMs,
-            inputTokens: usage.inputTokens,
-            outputTokens: usage.outputTokens,
-            cacheReadTokens: usage.cacheReadTokens,
+            // All per-turn values now (delta-corrected for cumulative
+            // providers above). Footer shows these directly.
+            inputTokens: turnInput,
+            outputTokens: turnOutput,
+            cacheReadTokens: turnCacheRead,
             totalContextTokens,
             contextWindow: config.claude.contextWindow,
             fresh: wasFresh,

package/migrations/0007_estimates_kind.sql

@@ -0,0 +1,2 @@
+ALTER TABLE `inbound` ADD `kind` text;--> statement-breakpoint
+CREATE INDEX `inbound_by_kind_done` ON `inbound` (`kind`,`status`);