agim-cli 1.0.1

package/dist/core/job-board.js

@@ -0,0 +1,379 @@
+// Job Board — persistent async job queue backed by SQLite
+//
+// Jobs survive restarts. Each job executes an agent invocation and stores the result.
+// Supports: create, list, get, cancel.
+//
+// Ownership (H5/M6/H7, code-review-2026-05-06):
+//   - Each row carries `creator_id` (the IM userId that originated the job)
+//     and `workspace_id`. Commands that the user runs through IM
+//     (`/job list|check|cancel|run`) MUST pass the caller's userId via
+//     opts.creatorId so users can't peek at or stomp on each others' jobs.
+//     Internal callers (REST `/api/jobs`, ACP server, scheduler) pass no
+//     filter and see every row — that's intentional, those entry-points
+//     are guarded by the web / API token.
+//   - Legacy rows (created before the migration) have creator_id = ''.
+//     They're treated as "ownerless / system" and visible to every owner-
+//     scoped query (so an upgrade doesn't appear to vanish the user's
+//     prior history).
+//   - pruneOldJobs() walks completed/failed/cancelled rows older than
+//     `IM_HUB_JOB_RETENTION_DAYS` (default 30) and deletes them; runs every
+//     6h via setInterval, mirroring audit-log.
+import { join } from 'node:path';
+import { logger as rootLogger } from './logger.js';
+import { eventBus } from './event-bus.js';
+import { createSqliteHelper } from './sqlite-helper.js';
+import { AGIM_HOME } from './agim-paths.js';
+const BOARD_DB = join(AGIM_HOME, 'jobs.db');
+/** Hard cap on a single job's accumulated result. A misbehaving agent (or a
+ * runaway tool that dumps a giant file) could otherwise keep filling the
+ * Buffer in {@link runJob} until the host OOMs and rage-stuff the SQLite TEXT
+ * column with the same payload. We cap at 1 MiB by default; chunks that would
+ * push past the cap are dropped and a truncation footer is appended. Override
+ * via env IMHUB_JOB_RESULT_MAX_BYTES. */
+function resolveMaxResultBytes() {
+    const raw = process.env.IMHUB_JOB_RESULT_MAX_BYTES;
+    if (raw) {
+        const n = parseInt(raw, 10);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return 1 * 1024 * 1024;
+}
+/** Hard cap on concurrent runJob() invocations. Spawning more than this
+ * would let a few /job run X requests OOM the host (each agent process
+ * carries hundreds of MB). Override via env IM_HUB_MAX_CONCURRENT_JOBS. */
+function resolveMaxConcurrent() {
+    const raw = process.env.IM_HUB_MAX_CONCURRENT_JOBS;
+    if (raw) {
+        const n = parseInt(raw, 10);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return 3;
+}
+// Running job controllers (for cancellation)
+const runningControllers = new Map();
+// Wait queue for jobs that arrived while at capacity. Each entry is the
+// resolver of a Promise the caller is awaiting on.
+const waitQueue = [];
+let activeJobs = 0;
+/**
+ * Reset jobs that were 'running' when the previous im-hub process died.
+ * Without this, those rows stay marked 'running' forever and every
+ * /job list shows ghosts.
+ */
+function reapStaleRunning(d) {
+    try {
+        const stmt = d.prepare("UPDATE jobs SET status='failed', error='im-hub restarted while running', completed_at=datetime('now') WHERE status='running'");
+        const info = stmt.run();
+        if (info.changes > 0) {
+            rootLogger.warn({ event: 'job-board.reap', stale: info.changes }, `Marked ${info.changes} stale running job(s) as failed`);
+        }
+    }
+    catch {
+        // best-effort; missing table is fine on first start
+    }
+}
+/**
+ * Idempotent column-add for ownership tracking. Run on every helper init —
+ * SQLite's ALTER TABLE ADD COLUMN throws "duplicate column name" if the
+ * column already exists, which we silently swallow. Cheaper than the full
+ * pragma table_info() inspection round-trip.
+ */
+function migrateOwnership(d) {
+    for (const col of ['creator_id', 'workspace_id']) {
+        try {
+            d.prepare(`ALTER TABLE jobs ADD COLUMN ${col} TEXT NOT NULL DEFAULT ''`).run();
+            rootLogger.info({ component: 'job-board', column: col, event: 'job-board.migration' }, `Added ${col} column to jobs table`);
+        }
+        catch {
+            // duplicate column — already migrated
+        }
+    }
+}
+/** Default number of days a completed/failed/cancelled job is retained. */
+function resolveRetentionDays() {
+    const raw = process.env.IM_HUB_JOB_RETENTION_DAYS;
+    if (raw) {
+        const n = parseInt(raw, 10);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return 30;
+}
+/** How often pruneOldJobs() is fired by the auto-sweep timer. 0 disables. */
+const RETENTION_SWEEP_INTERVAL_MS = 6 * 60 * 60 * 1000;
+let retentionSweepTimer = null;
+const helper = createSqliteHelper({
+    file: BOARD_DB,
+    component: 'job-board',
+    logger: rootLogger,
+    schema: `
+    CREATE TABLE IF NOT EXISTS jobs (
+      id            INTEGER PRIMARY KEY AUTOINCREMENT,
+      agent         TEXT    NOT NULL,
+      prompt        TEXT    NOT NULL,
+      status        TEXT    NOT NULL DEFAULT 'pending',
+      result        TEXT,
+      error         TEXT,
+      created_at    TEXT    NOT NULL DEFAULT (datetime('now')),
+      completed_at  TEXT,
+      creator_id    TEXT    NOT NULL DEFAULT '',
+      workspace_id  TEXT    NOT NULL DEFAULT ''
+    );
+    CREATE INDEX IF NOT EXISTS idx_jobs_created ON jobs(created_at);
+    CREATE INDEX IF NOT EXISTS idx_jobs_creator ON jobs(creator_id);
+    CREATE INDEX IF NOT EXISTS idx_jobs_status_created ON jobs(status, created_at);
+  `,
+    init: (d) => {
+        migrateOwnership(d);
+        // First-time / cold-start cleanup: any 'running' rows are leftover from a
+        // prior process that didn't get to finalize.
+        reapStaleRunning(d);
+        // Initial retention sweep + periodic timer. Mirrors audit-log shape so
+        // both tables stay bounded without operator intervention.
+        pruneOldJobs(d);
+        if (RETENTION_SWEEP_INTERVAL_MS > 0 && retentionSweepTimer === null) {
+            retentionSweepTimer = setInterval(() => {
+                const live = helper.get();
+                if (live)
+                    pruneOldJobs(live);
+            }, RETENTION_SWEEP_INTERVAL_MS);
+            if (typeof retentionSweepTimer === 'object' && retentionSweepTimer && 'unref' in retentionSweepTimer) {
+                retentionSweepTimer.unref();
+            }
+        }
+    },
+});
+/** Stop the retention sweep (used by tests + graceful shutdown). */
+export function stopJobRetentionSweep() {
+    if (retentionSweepTimer) {
+        clearInterval(retentionSweepTimer);
+        retentionSweepTimer = null;
+    }
+}
+/** Close the underlying SQLite handle. Called by cli.ts on graceful
+ *  shutdown so the WAL is checkpointed before exit (L2). */
+export function closeJobBoardDb() {
+    helper.close();
+}
+function getDb() {
+    return helper.get();
+}
+export function createJob(agent, prompt, opts = {}) {
+    const d = getDb();
+    if (!d)
+        throw new Error('Job board unavailable (SQLite not initialized)');
+    const row = d.prepare('INSERT INTO jobs (agent, prompt, status, creator_id, workspace_id) VALUES (?, ?, ?, ?, ?)').run(agent, prompt, 'pending', opts.creatorId || '', opts.workspaceId || '');
+    const id = Number(row.lastInsertRowid);
+    eventBus.publish({ type: 'job', phase: 'created', jobId: id, agent });
+    return id;
+}
+export function getJob(id, opts = {}) {
+    const d = getDb();
+    if (!d)
+        return null;
+    const row = (opts.creatorId !== undefined
+        ? d.prepare("SELECT * FROM jobs WHERE id = ? AND (creator_id = ? OR creator_id = '')")
+            .get(id, opts.creatorId)
+        : d.prepare('SELECT * FROM jobs WHERE id = ?').get(id));
+    return row || null;
+}
+export function listJobs(limit = 20, status, opts = {}) {
+    const d = getDb();
+    if (!d)
+        return [];
+    const safeLimit = Number.isFinite(limit) && limit > 0 ? Math.min(Math.floor(limit), 1000) : 20;
+    const conditions = [];
+    const params = [];
+    if (status) {
+        conditions.push('status = ?');
+        params.push(status);
+    }
+    if (opts.creatorId !== undefined) {
+        conditions.push("(creator_id = ? OR creator_id = '')");
+        params.push(opts.creatorId);
+    }
+    if (opts.agent) {
+        conditions.push('agent = ?');
+        params.push(opts.agent);
+    }
+    const where = conditions.length ? `WHERE ${conditions.join(' AND ')}` : '';
+    return d.prepare(`SELECT * FROM jobs ${where} ORDER BY created_at DESC LIMIT ?`)
+        .all(...params, safeLimit);
+}
+function updateJob(id, fields) {
+    const d = getDb();
+    if (!d)
+        return;
+    const sets = [];
+    const vals = [];
+    for (const [k, v] of Object.entries(fields)) {
+        if (v !== undefined) {
+            sets.push(`${k} = ?`);
+            vals.push(v);
+        }
+    }
+    if (!sets.length)
+        return;
+    d.prepare(`UPDATE jobs SET ${sets.join(', ')} WHERE id = ?`).run(...vals, id);
+}
+/**
+ * Acquire a job slot. Returns immediately when capacity available, otherwise
+ * queues the caller and returns a promise that resolves when a slot frees.
+ */
+async function acquireSlot() {
+    const max = resolveMaxConcurrent();
+    if (activeJobs < max) {
+        activeJobs++;
+        return;
+    }
+    await new Promise((resolve) => waitQueue.push(resolve));
+    activeJobs++;
+}
+function releaseSlot() {
+    activeJobs = Math.max(0, activeJobs - 1);
+    const next = waitQueue.shift();
+    if (next)
+        next();
+}
+export async function runJob(id, runner, logger) {
+    const job = getJob(id);
+    if (!job)
+        return;
+    // Block here if the job board is at capacity. The job stays 'pending' in
+    // SQLite while waiting — visible to /job list as queued.
+    await acquireSlot();
+    const controller = new AbortController();
+    runningControllers.set(id, controller);
+    updateJob(id, { status: 'running' });
+    eventBus.publish({ type: 'job', phase: 'started', jobId: id, agent: job.agent });
+    logger.info({ event: 'job.start', jobId: id, agent: job.agent, active: activeJobs });
+    let fullText = '';
+    let bytes = 0;
+    let droppedBytes = 0;
+    let truncated = false;
+    const cap = resolveMaxResultBytes();
+    try {
+        for await (const chunk of runner(job, logger, controller.signal)) {
+            if (controller.signal.aborted)
+                break;
+            const chunkBytes = Buffer.byteLength(chunk, 'utf-8');
+            if (truncated) {
+                droppedBytes += chunkBytes;
+                continue;
+            }
+            if (bytes + chunkBytes > cap) {
+                // Drop the entire over-cap chunk to keep the boundary on a UTF-8 /
+                // line boundary the producer chose; partial slicing risks splitting
+                // a multibyte char or a JSON object mid-event.
+                truncated = true;
+                droppedBytes += chunkBytes;
+                continue;
+            }
+            fullText += chunk;
+            bytes += chunkBytes;
+        }
+        if (truncated) {
+            const note = `\n\n[im-hub: result truncated — ${droppedBytes} bytes dropped after ${cap}-byte cap; raise IMHUB_JOB_RESULT_MAX_BYTES if needed]`;
+            fullText += note;
+            logger.warn({ event: 'job.result.truncated', jobId: id, droppedBytes, cap });
+        }
+        // Only update if not cancelled
+        if (!controller.signal.aborted) {
+            updateJob(id, { status: 'completed', result: fullText, completed_at: new Date().toISOString() });
+            eventBus.publish({ type: 'job', phase: 'completed', jobId: id, agent: job.agent });
+            logger.info({ event: 'job.complete', jobId: id, resultLen: fullText.length, truncated });
+        }
+        else {
+            updateJob(id, { status: 'cancelled', result: fullText || null, completed_at: new Date().toISOString() });
+            eventBus.publish({ type: 'job', phase: 'cancelled', jobId: id, agent: job.agent });
+            logger.info({ event: 'job.cancelled', jobId: id });
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const stack = err instanceof Error ? err.stack : undefined;
+        updateJob(id, { status: 'failed', error: msg, completed_at: new Date().toISOString() });
+        eventBus.publish({ type: 'job', phase: 'failed', jobId: id, agent: job.agent });
+        logger.error({ event: 'job.failed', jobId: id, error: msg, stack });
+    }
+    finally {
+        runningControllers.delete(id);
+        releaseSlot();
+    }
+}
+/** Test/diagnostic accessor: how many runJob invocations are currently in flight. */
+export function _activeJobCount() { return activeJobs; }
+/** Test/diagnostic accessor: the wait queue depth. */
+export function _waitQueueDepth() { return waitQueue.length; }
+/** Test-only: directly exercise the concurrency gate without SQLite. */
+export const _testSlot = { acquire: acquireSlot, release: releaseSlot };
+export function cancelJob(id, opts = {}) {
+    const job = getJob(id, opts);
+    if (!job || (job.status !== 'pending' && job.status !== 'running'))
+        return false;
+    const ctrl = runningControllers.get(id);
+    if (ctrl) {
+        ctrl.abort();
+        runningControllers.delete(id);
+    }
+    updateJob(id, { status: 'cancelled', completed_at: new Date().toISOString() });
+    eventBus.publish({ type: 'job', phase: 'cancelled', jobId: id, agent: job.agent });
+    return true;
+}
+/**
+ * Delete jobs that finished (completed / failed / cancelled) more than
+ * `daysRetention` days ago. 'pending' / 'running' rows are never pruned —
+ * a stalled-but-resumable job is the operator's call. Returns the row
+ * count so callers / tests can assert.
+ */
+export function pruneOldJobs(d = getDb(), daysRetention = resolveRetentionDays()) {
+    if (!d)
+        return 0;
+    try {
+        const info = d.prepare(`
+      DELETE FROM jobs
+      WHERE status IN ('completed', 'failed', 'cancelled')
+        AND completed_at IS NOT NULL
+        AND completed_at < datetime('now', ?)
+    `).run(`-${daysRetention} days`);
+        if (info.changes > 0) {
+            rootLogger.info({
+                component: 'job-board', event: 'job-board.pruned',
+                deleted: info.changes, days: daysRetention,
+            }, `Pruned ${info.changes} job row(s) older than ${daysRetention}d`);
+        }
+        return info.changes;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        rootLogger.warn({ component: 'job-board', event: 'job-board.prune.failed', error: msg }, 'job-board retention sweep failed');
+        return 0;
+    }
+}
+export function getJobStats() {
+    const empty = { total: 0, pending: 0, running: 0, completed: 0, failed: 0 };
+    const d = getDb();
+    if (!d)
+        return empty;
+    try {
+        const row = d.prepare(`
+      SELECT
+        COUNT(*) as total,
+        SUM(CASE WHEN status='pending' THEN 1 ELSE 0 END) as pending,
+        SUM(CASE WHEN status='running' THEN 1 ELSE 0 END) as running,
+        SUM(CASE WHEN status='completed' THEN 1 ELSE 0 END) as completed,
+        SUM(CASE WHEN status='failed' THEN 1 ELSE 0 END) as failed
+      FROM jobs
+    `).get();
+        return {
+            total: row.total || 0, pending: row.pending || 0, running: row.running || 0,
+            completed: row.completed || 0, failed: row.failed || 0,
+        };
+    }
+    catch {
+        return empty;
+    }
+}
+//# sourceMappingURL=job-board.js.map

package/dist/core/job-board.js.map

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

package/dist/core/location-context.d.ts

@@ -0,0 +1,32 @@
+export interface LocationContext {
+    /** WGS-84 latitude (caller is responsible for any GCJ-02→WGS-84 reversal). */
+    lat: number;
+    /** WGS-84 longitude. */
+    lng: number;
+    /** Optional accuracy in meters from the source platform. */
+    accuracy?: number;
+    /** Venue title (Telegram venue / Feishu location.name). */
+    venueLabel?: string;
+    /** Venue address line. */
+    venueAddress?: string;
+    /** Internal — used for TTL eviction. */
+    createdAt: number;
+}
+export declare function setLocationContext(threadKey: string, ctx: Omit<LocationContext, 'createdAt'>): void;
+/**
+ * Pop the location for this thread if any. Single-shot — consuming a
+ * location clears it, so a single share annotates at most one user turn.
+ */
+export declare function consumeLocationContext(threadKey: string): LocationContext | null;
+export declare function _sizeForTest(): number;
+export declare function _clearForTest(): void;
+/**
+ * Render a single-line annotation that we prepend to the user's next text
+ * message before sending it to the agent. Format is a structured tag the
+ * agent's system prompt knows about — see save_memo's tool description.
+ *
+ * Example:
+ *   [user just shared location: lat=30.275796, lng=120.127970, name="黄龙国际中心", address="学院路77号", accuracy_m=5]
+ */
+export declare function formatLocationAnnotation(c: LocationContext): string;
+//# sourceMappingURL=location-context.d.ts.map

package/dist/core/location-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"location-context.d.ts","sourceRoot":"","sources":["../../src/core/location-context.ts"],"names":[],"mappings":"AAwBA,MAAM,WAAW,eAAe;IAC9B,8EAA8E;IAC9E,GAAG,EAAE,MAAM,CAAA;IACX,wBAAwB;IACxB,GAAG,EAAE,MAAM,CAAA;IACX,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,0BAA0B;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAA;CAClB;AAUD,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,IAAI,CAAC,eAAe,EAAE,WAAW,CAAC,GACtC,IAAI,CAGN;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAKhF;AAED,wBAAgB,YAAY,IAAI,MAAM,CAAsB;AAC5D,wBAAgB,aAAa,IAAI,IAAI,CAAkB;AAEvD;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,eAAe,GAAG,MAAM,CAWnE"}

package/dist/core/location-context.js

@@ -0,0 +1,69 @@
+// location-context.ts — short-lived "user just shared GPS / venue" cache
+// per IM thread. Used by Telegram + Feishu adapters when the user sends a
+// native location/venue message: instead of running a deterministic
+// pending-reply + heuristic-extraction flow, we just stash the coords here
+// for the duration of one user turn, and cli.ts injects an annotation
+// into the user's NEXT text message before dispatching to the agent.
+//
+// Why this design (matches WeChat's H5-flow architecture):
+//   The agent already has full conversational context + LLM judgment;
+//   it's the right decision-maker for "should this be saved? as what?".
+//   The adapter's job is to surface the data, not to decide.
+//
+// Compared to the old pending-memo-location.ts:
+//   - No reply-decoding regex (cancel/confirm/free-form patterns)
+//   - No heuristic noun extraction (was producing "记下" / "一个好吃的日"
+//     style truncations)
+//   - No "y/n to skip" UX — the agent decides based on the user's actual
+//     follow-up message. "不用记" / silence / new topic all work naturally.
+//
+// The cache is purely additive: location is consumed on the next agent
+// dispatch in the same thread within 5 min. Beyond that, it evicts.
+const TTL_MS = 5 * 60 * 1000;
+const store = new Map();
+function evictExpired(now) {
+    for (const [k, v] of store) {
+        if (now - v.createdAt > TTL_MS)
+            store.delete(k);
+    }
+}
+export function setLocationContext(threadKey, ctx) {
+    evictExpired(Date.now());
+    store.set(threadKey, { ...ctx, createdAt: Date.now() });
+}
+/**
+ * Pop the location for this thread if any. Single-shot — consuming a
+ * location clears it, so a single share annotates at most one user turn.
+ */
+export function consumeLocationContext(threadKey) {
+    evictExpired(Date.now());
+    const c = store.get(threadKey);
+    if (c)
+        store.delete(threadKey);
+    return c ?? null;
+}
+export function _sizeForTest() { return store.size; }
+export function _clearForTest() { store.clear(); }
+/**
+ * Render a single-line annotation that we prepend to the user's next text
+ * message before sending it to the agent. Format is a structured tag the
+ * agent's system prompt knows about — see save_memo's tool description.
+ *
+ * Example:
+ *   [user just shared location: lat=30.275796, lng=120.127970, name="黄龙国际中心", address="学院路77号", accuracy_m=5]
+ */
+export function formatLocationAnnotation(c) {
+    const parts = [
+        `lat=${c.lat.toFixed(6)}`,
+        `lng=${c.lng.toFixed(6)}`,
+    ];
+    if (c.venueLabel)
+        parts.push(`name=${JSON.stringify(c.venueLabel)}`);
+    if (c.venueAddress)
+        parts.push(`address=${JSON.stringify(c.venueAddress)}`);
+    if (typeof c.accuracy === 'number' && Number.isFinite(c.accuracy)) {
+        parts.push(`accuracy_m=${Math.round(c.accuracy)}`);
+    }
+    return `[user just shared location: ${parts.join(', ')}]`;
+}
+//# sourceMappingURL=location-context.js.map

package/dist/core/location-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"location-context.js","sourceRoot":"","sources":["../../src/core/location-context.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,0EAA0E;AAC1E,oEAAoE;AACpE,2EAA2E;AAC3E,sEAAsE;AACtE,qEAAqE;AACrE,EAAE;AACF,2DAA2D;AAC3D,sEAAsE;AACtE,wEAAwE;AACxE,6DAA6D;AAC7D,EAAE;AACF,gDAAgD;AAChD,kEAAkE;AAClE,kEAAkE;AAClE,yBAAyB;AACzB,yEAAyE;AACzE,yEAAyE;AACzE,EAAE;AACF,uEAAuE;AACvE,oEAAoE;AAEpE,MAAM,MAAM,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAA;AAiB5B,MAAM,KAAK,GAAG,IAAI,GAAG,EAA2B,CAAA;AAEhD,SAAS,YAAY,CAAC,GAAW;IAC/B,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC;QAC3B,IAAI,GAAG,GAAG,CAAC,CAAC,SAAS,GAAG,MAAM;YAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;IACjD,CAAC;AACH,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,SAAiB,EACjB,GAAuC;IAEvC,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAA;IACxB,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,GAAG,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;AACzD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,sBAAsB,CAAC,SAAiB;IACtD,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAA;IACxB,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;IAC9B,IAAI,CAAC;QAAE,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;IAC9B,OAAO,CAAC,IAAI,IAAI,CAAA;AAClB,CAAC;AAED,MAAM,UAAU,YAAY,KAAa,OAAO,KAAK,CAAC,IAAI,CAAA,CAAC,CAAC;AAC5D,MAAM,UAAU,aAAa,KAAW,KAAK,CAAC,KAAK,EAAE,CAAA,CAAC,CAAC;AAEvD;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CAAC,CAAkB;IACzD,MAAM,KAAK,GAAa;QACtB,OAAO,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;QACzB,OAAO,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE;KAC1B,CAAA;IACD,IAAI,CAAC,CAAC,UAAU;QAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,EAAE,CAAC,CAAA;IACpE,IAAI,CAAC,CAAC,YAAY;QAAE,KAAK,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,CAAC,CAAA;IAC3E,IAAI,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;QAClE,KAAK,CAAC,IAAI,CAAC,cAAc,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAA;IACpD,CAAC;IACD,OAAO,+BAA+B,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAA;AAC3D,CAAC"}

package/dist/core/location-token.d.ts

@@ -0,0 +1,57 @@
+export interface TokenContext {
+    platform: string;
+    channelId: string;
+    threadId: string;
+    userId: string;
+}
+/**
+ * Optional metadata the issuer may attach.
+ *
+ *  - `what`   : label shown on the H5 page and used as the new memo's
+ *               `what` field if the token's flow CREATES a memo.
+ *  - `memoId` : when set, the H5 callback UPDATES an existing memo's
+ *               where_lat / where_lng instead of creating a new one.
+ *               Used when agent already created the memo via save_memo
+ *               and is now augmenting it with GPS.
+ *
+ * Server-side only — clients (the H5 page) can READ what/memoId via
+ * /api/loc/info but never inject them.
+ */
+export interface TokenMeta {
+    what?: string;
+    memoId?: number;
+}
+export declare function issueToken(ctx: TokenContext, meta?: TokenMeta): {
+    token: string;
+    expiresAt: number;
+    ttlSeconds: number;
+};
+/** Read-only peek — used by GET /api/loc/info so the H5 page can render
+ *  "正在记录: <what>" without consuming the token. Returns null when the
+ *  token is unknown or expired (auto-evicts expired). */
+export declare function peekToken(token: string): {
+    ctx: TokenContext;
+    what: string;
+    memoId: number | null;
+    expiresAt: number;
+} | null;
+export type ConsumeResult = {
+    ok: true;
+    ctx: TokenContext;
+    what: string;
+    memoId: number | null;
+} | {
+    ok: false;
+    reason: 'unknown' | 'expired';
+};
+/**
+ * Consume a token — single-shot. After this call, the token is removed
+ * from the store regardless of outcome (`expired` tokens are also dropped
+ * to prevent retry brute-force scanning).
+ */
+export declare function consumeToken(token: string): ConsumeResult;
+/** Test/diagnostic helper. */
+export declare function _pendingCount(): number;
+export declare function _clearAll(): void;
+export declare function _stopSweep(): void;
+//# sourceMappingURL=location-token.d.ts.map

package/dist/core/location-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"location-token.d.ts","sourceRoot":"","sources":["../../src/core/location-token.ts"],"names":[],"mappings":"AAiCA,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AA8BD,wBAAgB,UAAU,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,GAAE,SAAc,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAsB5H;AAED;;yDAEyD;AACzD,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAa7H;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,YAAY,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GACpE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,SAAS,GAAG,SAAS,CAAA;CAAE,CAAA;AAEhD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAsBzD;AAED,8BAA8B;AAC9B,wBAAgB,aAAa,IAAI,MAAM,CAAuB;AAC9D,wBAAgB,SAAS,IAAI,IAAI,CAAmB;AACpD,wBAAgB,UAAU,IAAI,IAAI,CAEjC"}