agim-cli 1.2.44 → 1.2.48

package/dist/core/goals.js

@@ -0,0 +1,361 @@
+// goals — sustained-objective tracking for IM threads (P0 #2).
+//
+// Distinct from reminders / cron / heartbeats:
+//   - `/remind`     — one-shot: fire at time T, deliver text, done.
+//   - `/cron`       — repeating: same fire shape, no agent state across runs.
+//   - `/heartbeat`  — periodic self-check that asks the agent if anything
+//                     is worth doing right now (binding body = what to
+//                     watch). Each tick is independent.
+//   - `/goal`       — sustained MULTI-TURN objective: "ship v1.3.0 by
+//                     Friday" / "research X over the next week". The
+//                     agent sees the active goal injected into EVERY
+//                     turn's prompt so it can keep the user on-mission
+//                     across many back-and-forths. Users / agent log
+//                     progress notes; on completion the row stays for
+//                     historical browsing.
+//
+// One ACTIVE goal per thread at a time. Older goals are kept on disk
+// for /goal list browsing but never injected into prompts.
+//
+// Storage: ~/.agim/goals.db (SQLite), same fail-soft helper as the
+// rest of agim's per-user state.
+import { join } from 'node:path';
+import { AGIM_HOME } from './agim-paths.js';
+import { logger as rootLogger } from './logger.js';
+import { createSqliteHelper } from './sqlite-helper.js';
+const GOALS_DB = process.env.IMHUB_GOALS_DB ?? join(AGIM_HOME, 'goals.db');
+/** Hard caps. Goals are user-typed prose; tight limits keep prompt
+ *  injection from blowing the context window on a single thread. */
+export const MAX_TITLE_CHARS = 200;
+export const MAX_BODY_CHARS = 4_000;
+export const MAX_PROGRESS_NOTE_CHARS = 500;
+export const MAX_PROGRESS_NOTES_INJECTED = 5; // most recent
+/** Most-recent N progress notes shown in /goal show output. */
+const MAX_PROGRESS_NOTES_LISTED = 20;
+const helper = createSqliteHelper({
+    file: GOALS_DB,
+    component: 'goals',
+    logger: rootLogger,
+    schema: `
+    CREATE TABLE IF NOT EXISTS goals (
+      id            INTEGER PRIMARY KEY AUTOINCREMENT,
+      platform      TEXT    NOT NULL,
+      channel_id    TEXT    NOT NULL,
+      thread_id     TEXT    NOT NULL,
+      user_id       TEXT    NOT NULL DEFAULT '',
+      title         TEXT    NOT NULL,
+      body          TEXT    NOT NULL DEFAULT '',
+      status        TEXT    NOT NULL DEFAULT 'active',
+      progress_log  TEXT    NOT NULL DEFAULT '[]',
+      created_at    TEXT    NOT NULL DEFAULT (datetime('now')),
+      updated_at    TEXT    NOT NULL DEFAULT (datetime('now')),
+      closed_at     TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_goals_thread   ON goals(platform, channel_id, thread_id, status);
+    CREATE INDEX IF NOT EXISTS idx_goals_status   ON goals(status, updated_at);
+    CREATE INDEX IF NOT EXISTS idx_goals_owner    ON goals(platform, user_id, status);
+  `,
+});
+function getDb() {
+    return helper.get();
+}
+function rowFromRaw(r) {
+    let progress = [];
+    try {
+        const parsed = JSON.parse(r.progress_log || '[]');
+        if (Array.isArray(parsed)) {
+            progress = parsed
+                .filter((n) => (typeof n === 'object' && n !== null &&
+                typeof n.ts === 'string' &&
+                typeof n.by === 'string' &&
+                typeof n.text === 'string'));
+        }
+    }
+    catch { /* malformed JSON; fall back to empty list */ }
+    return {
+        id: r.id,
+        platform: r.platform,
+        channelId: r.channel_id,
+        threadId: r.thread_id,
+        userId: r.user_id,
+        title: r.title,
+        body: r.body,
+        status: (r.status || 'active'),
+        progressLog: progress,
+        createdAt: r.created_at,
+        updatedAt: r.updated_at,
+        closedAt: r.closed_at,
+    };
+}
+/**
+ * Set (or replace) the ACTIVE goal for a thread. Idempotent semantics:
+ * if there's already an active goal, it's auto-paused first (kept in
+ * the table) and a fresh row replaces it. This avoids accidental
+ * silent drops of partially-tracked work — the operator can /goal
+ * list to find paused predecessors and /goal resume <id> if they
+ * changed their mind.
+ */
+export function setActiveGoal(input) {
+    const d = getDb();
+    if (!d)
+        return null;
+    const title = input.title.trim().slice(0, MAX_TITLE_CHARS);
+    const body = (input.body ?? '').trim().slice(0, MAX_BODY_CHARS);
+    if (!title)
+        return null;
+    try {
+        // Auto-pause any existing ACTIVE goal in this thread so there's
+        // never more than one row to inject. Older paused/completed
+        // rows are untouched.
+        d.prepare(`
+      UPDATE goals SET
+        status = 'paused',
+        updated_at = datetime('now')
+      WHERE platform = ? AND channel_id = ? AND thread_id = ? AND status = 'active'
+    `).run(input.platform, input.channelId, input.threadId);
+        const info = d.prepare(`
+      INSERT INTO goals (platform, channel_id, thread_id, user_id, title, body, status, progress_log)
+      VALUES (?, ?, ?, ?, ?, ?, 'active', '[]')
+    `).run(input.platform, input.channelId, input.threadId, input.userId, title, body);
+        return getGoalById(Number(info.lastInsertRowid));
+    }
+    catch (err) {
+        rootLogger.warn({ event: 'goals.set_active_failed', err: String(err) });
+        return null;
+    }
+}
+/** Append a progress note to a goal. Caller picks `by` (typically
+ *  'user' for /goal progress, 'agent' for future MCP tool call,
+ *  'system' for status transitions). */
+export function appendProgress(goalId, by, text) {
+    const d = getDb();
+    if (!d)
+        return false;
+    const note = {
+        ts: new Date().toISOString(),
+        by,
+        text: text.trim().slice(0, MAX_PROGRESS_NOTE_CHARS),
+    };
+    if (!note.text)
+        return false;
+    try {
+        // Read-modify-write inside one transaction so two near-simultaneous
+        // /goal progress calls don't clobber each other.
+        const tx = d.transaction(() => {
+            const row = d.prepare(`SELECT progress_log FROM goals WHERE id = ?`).get(goalId);
+            if (!row)
+                return false;
+            let list;
+            try {
+                const parsed = JSON.parse(row.progress_log || '[]');
+                list = Array.isArray(parsed) ? parsed : [];
+            }
+            catch {
+                list = [];
+            }
+            list.push(note);
+            d.prepare(`
+        UPDATE goals SET progress_log = ?, updated_at = datetime('now')
+        WHERE id = ?
+      `).run(JSON.stringify(list), goalId);
+            return true;
+        });
+        return tx();
+    }
+    catch (err) {
+        rootLogger.warn({ event: 'goals.append_progress_failed', err: String(err) });
+        return false;
+    }
+}
+export function updateStatus(goalId, status) {
+    const d = getDb();
+    if (!d)
+        return false;
+    const isClose = status === 'completed' || status === 'cancelled';
+    try {
+        const info = d.prepare(`
+      UPDATE goals SET
+        status = ?,
+        updated_at = datetime('now'),
+        closed_at = CASE WHEN ? THEN datetime('now') ELSE closed_at END
+      WHERE id = ?
+    `).run(status, isClose ? 1 : 0, goalId);
+        return info.changes > 0;
+    }
+    catch (err) {
+        rootLogger.warn({ event: 'goals.update_status_failed', err: String(err) });
+        return false;
+    }
+}
+/** Resume a paused goal — also auto-pauses any currently-active goal
+ *  in the same thread so there's never more than one active. */
+export function resumeGoal(goalId) {
+    const d = getDb();
+    if (!d)
+        return false;
+    try {
+        const row = d.prepare(`SELECT platform, channel_id, thread_id, status FROM goals WHERE id = ?`)
+            .get(goalId);
+        if (!row)
+            return false;
+        if (row.status === 'completed' || row.status === 'cancelled')
+            return false;
+        const tx = d.transaction(() => {
+            d.prepare(`
+        UPDATE goals SET status = 'paused', updated_at = datetime('now')
+        WHERE platform = ? AND channel_id = ? AND thread_id = ? AND status = 'active'
+      `).run(row.platform, row.channel_id, row.thread_id);
+            d.prepare(`
+        UPDATE goals SET status = 'active', updated_at = datetime('now')
+        WHERE id = ?
+      `).run(goalId);
+        });
+        tx();
+        return true;
+    }
+    catch (err) {
+        rootLogger.warn({ event: 'goals.resume_failed', err: String(err) });
+        return false;
+    }
+}
+export function getGoalById(id) {
+    const d = getDb();
+    if (!d)
+        return null;
+    try {
+        const row = d.prepare(`SELECT * FROM goals WHERE id = ?`).get(id);
+        return row ? rowFromRaw(row) : null;
+    }
+    catch (err) {
+        rootLogger.warn({ event: 'goals.get_by_id_failed', err: String(err) });
+        return null;
+    }
+}
+/** The single active goal for a thread (or null if none). */
+export function getActiveGoal(platform, channelId, threadId) {
+    const d = getDb();
+    if (!d)
+        return null;
+    try {
+        const row = d.prepare(`
+      SELECT * FROM goals
+      WHERE platform = ? AND channel_id = ? AND thread_id = ? AND status = 'active'
+      ORDER BY id DESC LIMIT 1
+    `).get(platform, channelId, threadId);
+        return row ? rowFromRaw(row) : null;
+    }
+    catch (err) {
+        rootLogger.warn({ event: 'goals.get_active_failed', err: String(err) });
+        return null;
+    }
+}
+/** All goals (any status) for a thread, newest first. Used by /goal list. */
+export function listGoalsForThread(platform, channelId, threadId, limit = 20) {
+    const d = getDb();
+    if (!d)
+        return [];
+    try {
+        const rows = d.prepare(`
+      SELECT * FROM goals
+      WHERE platform = ? AND channel_id = ? AND thread_id = ?
+      ORDER BY id DESC LIMIT ?
+    `).all(platform, channelId, threadId, limit);
+        return rows.map(rowFromRaw);
+    }
+    catch (err) {
+        rootLogger.warn({ event: 'goals.list_thread_failed', err: String(err) });
+        return [];
+    }
+}
+/** Admin / debug — every active goal across the install. */
+export function listAllActiveGoals() {
+    const d = getDb();
+    if (!d)
+        return [];
+    try {
+        const rows = d.prepare(`
+      SELECT * FROM goals WHERE status = 'active' ORDER BY id ASC
+    `).all();
+        return rows.map(rowFromRaw);
+    }
+    catch (err) {
+        rootLogger.warn({ event: 'goals.list_all_failed', err: String(err) });
+        return [];
+    }
+}
+/**
+ * Build the per-turn prompt-prefix snippet for the active goal. Bounded
+ * to ~MAX_PROGRESS_NOTES_INJECTED recent notes + truncated body so a
+ * verbose goal doesn't dominate the prompt budget. Empty string when no
+ * active goal — router treats falsy snippets as "skip this block".
+ *
+ * The snippet is OVER THE WIRE only — it's prepended to the prompt the
+ * agent sees but NOT stored in session history, so it doesn't bloat the
+ * persisted conversation.
+ */
+export function buildGoalSnippet(platform, channelId, threadId) {
+    const goal = getActiveGoal(platform, channelId, threadId);
+    if (!goal)
+        return '';
+    const lines = [];
+    lines.push(`[agim context — active goal #${goal.id} for this thread]`);
+    lines.push(`Title: ${goal.title}`);
+    if (goal.body) {
+        const truncated = goal.body.length > 800 ? `${goal.body.slice(0, 800)}…` : goal.body;
+        lines.push('Body:');
+        lines.push(truncated);
+    }
+    if (goal.progressLog.length > 0) {
+        lines.push('Recent progress:');
+        const recent = goal.progressLog.slice(-MAX_PROGRESS_NOTES_INJECTED);
+        for (const note of recent) {
+            // Strip seconds/ms for compactness; UTC suffix omitted (already understood).
+            const t = note.ts.slice(0, 16).replace('T', ' ');
+            lines.push(`  - ${t} (${note.by}) ${note.text}`);
+        }
+    }
+    lines.push('Use this goal to keep replies on-mission. Ignore if the user explicitly changes topic.');
+    lines.push('');
+    return lines.join('\n');
+}
+/** For /goal show — render an operator-facing summary including ALL
+ *  retained progress notes (capped at MAX_PROGRESS_NOTES_LISTED so the
+ *  IM bubble doesn't explode). */
+export function formatGoalShow(goal) {
+    const out = [];
+    const statusFlag = ({
+        active: '✅ active',
+        paused: '⏸ paused',
+        completed: '🎯 completed',
+        cancelled: '✖ cancelled',
+    })[goal.status];
+    out.push(`🎯 Goal #${goal.id} — ${statusFlag}`);
+    out.push(`Title: ${goal.title}`);
+    out.push(`Updated: ${goal.updatedAt} UTC`);
+    if (goal.closedAt)
+        out.push(`Closed:  ${goal.closedAt} UTC`);
+    if (goal.body) {
+        out.push('');
+        out.push('Body:');
+        out.push('```');
+        out.push(goal.body);
+        out.push('```');
+    }
+    if (goal.progressLog.length > 0) {
+        out.push('');
+        out.push(`Progress (${goal.progressLog.length} notes):`);
+        const recent = goal.progressLog.slice(-MAX_PROGRESS_NOTES_LISTED).reverse();
+        for (const n of recent) {
+            out.push(`  - ${n.ts.slice(0, 19).replace('T', ' ')} UTC (${n.by}) ${n.text}`);
+        }
+    }
+    return out.join('\n');
+}
+/** Test-only. Drops everything; safe to call repeatedly in beforeEach. */
+export function _truncateForTests() {
+    const d = getDb();
+    if (!d)
+        return;
+    d.exec('DELETE FROM goals');
+}
+//# sourceMappingURL=goals.js.map

package/dist/core/goals.js.map

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

package/dist/core/heartbeat-store.d.ts

@@ -0,0 +1,90 @@
+/** Per-thread tick recurrence, in minutes. The default lines up with
+ *  nanobot's 30-min cadence; operators can override per binding with
+ *  `/heartbeat interval N` or the IMHUB_HEARTBEAT_DEFAULT_INTERVAL env. */
+export declare const DEFAULT_INTERVAL_MIN = 30;
+/** Hard lower bound on the recurrence. 1-minute heartbeats are almost
+ *  always a misconfiguration (the agent burns through API calls and
+ *  there's no time for the previous tick to even finish). */
+export declare const MIN_INTERVAL_MIN = 5;
+/** Hard upper bound — 24h. Above this just use cron + reminders. */
+export declare const MAX_INTERVAL_MIN: number;
+/** Max characters in a heartbeat body. Keeps prompt size bounded; the
+ *  body is the entire context the cheap decide-step LLM sees, so
+ *  unbounded text would silently blow the context window. */
+export declare const MAX_BODY_CHARS = 8000;
+/** Tick statuses recorded per attempt. */
+export type TickStatus = 'pending' | 'skipped' | 'delivered' | 'suppressed' | 'no-agent' | 'failed';
+export interface HeartbeatRow {
+    id: number;
+    /** IM coordinates — the binding scope. */
+    platform: string;
+    channelId: string;
+    threadId: string;
+    /** Owner of this binding (the IM user who ran /heartbeat bind). Used
+     *  for audit and for picking the same agent the user is chatting
+     *  with at tick time. */
+    userId: string;
+    /** Markdown body — what the decide-step LLM and the execute-step
+     *  agent reason against. Plain UTF-8; users can include lists, code
+     *  fences, whatever they want. Max MAX_BODY_CHARS. */
+    body: string;
+    /** Tick recurrence (minutes). MIN_INTERVAL_MIN ≤ x ≤ MAX_INTERVAL_MIN. */
+    intervalMinutes: number;
+    /** Soft kill-switch. Disabled rows survive but never tick. */
+    enabled: boolean;
+    /** ISO timestamp of the last attempted tick (null = never ticked). */
+    lastTickAt: string | null;
+    /** Status of that last tick. */
+    lastStatus: TickStatus;
+    /** Operator-facing one-liner from the last tick. */
+    lastReason: string;
+    /** First MAX_PREVIEW_CHARS of the last successfully delivered text. */
+    lastTextPreview: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Read the operator-provided default interval (env override or constant). */
+export declare function defaultIntervalMinutes(): number;
+/**
+ * Create or replace the heartbeat for a thread. UPSERT semantics — one
+ * binding per thread, calling bind() again overwrites the body and
+ * resets last_tick_at so the new body takes effect on the next tick
+ * (not 30 min later).
+ */
+export declare function upsertBinding(input: {
+    platform: string;
+    channelId: string;
+    threadId: string;
+    userId: string;
+    body: string;
+    intervalMinutes?: number;
+}): HeartbeatRow | null;
+/** Disable (don't delete) a binding for the given thread. */
+export declare function disableBinding(platform: string, channelId: string, threadId: string): boolean;
+/** Soft-enable an existing binding (no-op if missing). */
+export declare function enableBinding(platform: string, channelId: string, threadId: string): boolean;
+/** Replace the interval for an existing binding (no-op if missing). */
+export declare function updateInterval(platform: string, channelId: string, threadId: string, intervalMinutes: number): boolean;
+/** Stamp the outcome of a tick. Caller is the scheduler / runForBinding. */
+export declare function recordTick(input: {
+    id: number;
+    status: TickStatus;
+    reason: string;
+    /** When delivered, the (truncated) body text. Ignored for non-delivered. */
+    deliveredText?: string;
+}): void;
+export declare function getBinding(platform: string, channelId: string, threadId: string): HeartbeatRow | null;
+/** All bindings, regardless of enabled state. Admin-facing /heartbeat list. */
+export declare function listAllBindings(): HeartbeatRow[];
+/**
+ * All enabled bindings whose next tick is due. "Due" = `last_tick_at IS
+ * NULL` OR `datetime(last_tick_at) <= datetime('now', '-N minutes')`.
+ *
+ * Each row carries its own interval, so we can't precompute a single
+ * cutoff — the SQL filter checks per-row using interval_minutes.
+ */
+export declare function listDueBindings(): HeartbeatRow[];
+/** Strictly for tests: drop the table contents. NEVER call from runtime
+ *  paths — the alternative is `disableBinding` per row. */
+export declare function _truncateForTests(): void;
+//# sourceMappingURL=heartbeat-store.d.ts.map

package/dist/core/heartbeat-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat-store.d.ts","sourceRoot":"","sources":["../../src/core/heartbeat-store.ts"],"names":[],"mappings":"AA2BA;;2EAE2E;AAC3E,eAAO,MAAM,oBAAoB,KAAK,CAAA;AAEtC;;6DAE6D;AAC7D,eAAO,MAAM,gBAAgB,IAAI,CAAA;AAEjC,oEAAoE;AACpE,eAAO,MAAM,gBAAgB,QAAU,CAAA;AAEvC;;6DAE6D;AAC7D,eAAO,MAAM,cAAc,OAAQ,CAAA;AAMnC,0CAA0C;AAC1C,MAAM,MAAM,UAAU,GAClB,SAAS,GACT,SAAS,GACT,WAAW,GACX,YAAY,GACZ,UAAU,GACV,QAAQ,CAAA;AAEZ,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB;;6BAEyB;IACzB,MAAM,EAAE,MAAM,CAAA;IACd;;0DAEsD;IACtD,IAAI,EAAE,MAAM,CAAA;IACZ,0EAA0E;IAC1E,eAAe,EAAE,MAAM,CAAA;IACvB,8DAA8D;IAC9D,OAAO,EAAE,OAAO,CAAA;IAChB,sEAAsE;IACtE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IACzB,gCAAgC;IAChC,UAAU,EAAE,UAAU,CAAA;IACtB,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAA;IAClB,uEAAuE;IACvE,eAAe,EAAE,MAAM,CAAA;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;CAClB;AAqED,8EAA8E;AAC9E,wBAAgB,sBAAsB,IAAI,MAAM,CAS/C;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACnC,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB,GAAG,YAAY,GAAG,IAAI,CAmCtB;AAED,6DAA6D;AAC7D,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAa7F;AAED,0DAA0D;AAC1D,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAa5F;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EACrD,eAAe,EAAE,MAAM,GACtB,OAAO,CAeT;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,KAAK,EAAE;IAChC,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,UAAU,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,4EAA4E;IAC5E,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,GAAG,IAAI,CA4BP;AAED,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAarG;AAED,+EAA+E;AAC/E,wBAAgB,eAAe,IAAI,YAAY,EAAE,CAUhD;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,IAAI,YAAY,EAAE,CAmBhD;AAED;2DAC2D;AAC3D,wBAAgB,iBAAiB,IAAI,IAAI,CAIxC"}