@desplega.ai/agent-swarm 1.79.0 → 1.79.2

package/src/be/db.ts

@@ -34,6 +34,8 @@ import type {
   InboxMessage,
   InboxMessageStatus,
   InputValue,
+  KvEntry,
+  KvValueType,
   McpServer,
   McpServerScope,
   McpServerTransport,
@@ -6264,6 +6266,7 @@ type PageRow = {
   needsCredentials: string | null;
   createdAt: string;
   updatedAt: string;
+  view_count: number;
 };
 
 function rowToPage(row: PageRow): Page {
@@ -6280,6 +6283,7 @@ function rowToPage(row: PageRow): Page {
     needsCredentials: row.needsCredentials
       ? (JSON.parse(row.needsCredentials) as string[])
       : undefined,
+    viewCount: typeof row.view_count === "number" ? row.view_count : 0,
     createdAt: normalizeDateRequired(row.createdAt),
     updatedAt: normalizeDateRequired(row.updatedAt),
   };
@@ -6422,6 +6426,19 @@ export function deletePage(id: string): boolean {
   return result.changes > 0;
 }
 
+/**
+ * Bump the `view_count` counter on a page by 1. Called from `pages-public.ts`
+ * on every successful 200 from `GET /p/:id` (HTML inline serve) and
+ * `GET /p/:id.json` (JSON metadata fetch). No-op when the page doesn't
+ * exist — caller already guards on `getPage(id)` before reaching the bump
+ * path, so this only fires for valid ids. Wrapped in try/catch by the
+ * caller so an unexpected DB error never breaks page serving.
+ */
+export function incrementPageViewCount(id: string): boolean {
+  const result = getDb().run("UPDATE pages SET view_count = view_count + 1 WHERE id = ?", [id]);
+  return result.changes > 0;
+}
+
 type PageVersionRow = {
   id: string;
   pageId: string;
@@ -9678,3 +9695,295 @@ export function hasFirstCompletedTask(): boolean {
     .get();
   return row !== null;
 }
+
+// ============================================================================
+// KV store (kv_entries)
+// ============================================================================
+//
+// Namespaced key/value with lazy expire-on-read TTL. See:
+//   - src/be/migrations/061_kv_store.sql (schema)
+//   - src/http/kv.ts                     (REST surface + namespace resolution)
+//   - src/tools/kv/*                     (MCP surface)
+//
+// Conventions:
+//   - All sizing / regex validation happens at the HTTP / MCP boundary so the
+//     helpers below can assume well-formed inputs.
+//   - `value` is stored verbatim in TEXT; helpers decode based on value_type.
+//   - "now" is `unixepoch('subsec') * 1000` (unix-ms), consistent with the
+//     migration's DEFAULTs — using JS `Date.now()` for the few helpers that
+//     need to mention an explicit timestamp keeps the math identical at ms
+//     resolution.
+
+interface KvRow {
+  namespace: string;
+  key: string;
+  value: string;
+  value_type: KvValueType;
+  expires_at: number | null;
+  created_at: number;
+  updated_at: number;
+}
+
+function decodeKvRow(row: KvRow): KvEntry {
+  let value: unknown;
+  if (row.value_type === "json") {
+    try {
+      value = JSON.parse(row.value);
+    } catch {
+      // Stored JSON is corrupt — surface as raw string rather than throwing
+      // on read; the row is still recoverable by the caller.
+      value = row.value;
+    }
+  } else if (row.value_type === "integer") {
+    value = Number(row.value);
+  } else {
+    value = row.value;
+  }
+  return {
+    namespace: row.namespace,
+    key: row.key,
+    value,
+    valueType: row.value_type,
+    expiresAt: row.expires_at,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function encodeKvValue(value: unknown, valueType: KvValueType): string {
+  if (valueType === "json") {
+    return JSON.stringify(value);
+  }
+  if (valueType === "integer") {
+    if (typeof value === "number") {
+      if (!Number.isInteger(value) || !Number.isSafeInteger(value)) {
+        throw new Error("integer value must be a JS-safe integer");
+      }
+      return String(value);
+    }
+    if (typeof value === "string" && /^-?\d+$/.test(value)) {
+      return value;
+    }
+    throw new Error("integer value must be a JS-safe integer");
+  }
+  // 'string'
+  if (typeof value !== "string") {
+    throw new Error("string value must be a string");
+  }
+  return value;
+}
+
+/**
+ * Get a single KV entry. Returns null if missing OR expired; expired rows are
+ * deleted inline (single-row DELETE WHERE) so the row count stays bounded over
+ * time without a background sweeper.
+ */
+export function getKv(namespace: string, key: string): KvEntry | null {
+  const row = getDb()
+    .prepare<KvRow, [string, string]>(
+      `SELECT namespace, key, value, value_type, expires_at, created_at, updated_at
+         FROM kv_entries WHERE namespace = ? AND key = ?`,
+    )
+    .get(namespace, key);
+  if (!row) return null;
+  if (row.expires_at !== null && row.expires_at <= Date.now()) {
+    getDb()
+      .prepare<unknown, [string, string]>(`DELETE FROM kv_entries WHERE namespace = ? AND key = ?`)
+      .run(namespace, key);
+    return null;
+  }
+  return decodeKvRow(row);
+}
+
+/**
+ * Upsert a KV entry. Caller passes the decoded value + valueType; we encode
+ * before storing. `expiresAt` is unix-ms (NULL means no expiry).
+ *
+ * If the key already exists with a different `valueType` we still overwrite —
+ * INCR is the only collision-sensitive op and it does its own check.
+ */
+export function upsertKv(input: {
+  namespace: string;
+  key: string;
+  value: unknown;
+  valueType: KvValueType;
+  expiresAt?: number | null;
+}): KvEntry {
+  const encoded = encodeKvValue(input.value, input.valueType);
+  const expiresAt = input.expiresAt ?? null;
+  const now = Date.now();
+  const row = getDb()
+    .prepare<KvRow, [string, string, string, KvValueType, number | null, number, number]>(
+      `INSERT INTO kv_entries (namespace, key, value, value_type, expires_at, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(namespace, key) DO UPDATE SET
+         value = excluded.value,
+         value_type = excluded.value_type,
+         expires_at = excluded.expires_at,
+         updated_at = excluded.updated_at
+       RETURNING namespace, key, value, value_type, expires_at, created_at, updated_at`,
+    )
+    .get(input.namespace, input.key, encoded, input.valueType, expiresAt, now, now);
+  if (!row) throw new Error("Failed to upsert kv entry");
+  return decodeKvRow(row);
+}
+
+/**
+ * Delete a KV entry. Returns true if a row was removed, false if nothing
+ * existed. Does not differentiate expired-but-not-yet-swept from never-existed.
+ */
+export function deleteKv(namespace: string, key: string): boolean {
+  const result = getDb()
+    .prepare<unknown, [string, string]>(`DELETE FROM kv_entries WHERE namespace = ? AND key = ?`)
+    .run(namespace, key);
+  return result.changes > 0;
+}
+
+export class KvTypeCollisionError extends Error {
+  readonly existingType: KvValueType;
+  constructor(existingType: KvValueType) {
+    super(`Cannot INCR a key with value_type '${existingType}'`);
+    this.name = "KvTypeCollisionError";
+    this.existingType = existingType;
+  }
+}
+
+/**
+ * Atomically increment an integer KV entry. Creates the entry (set to `by`)
+ * if it doesn't exist or has expired. Throws `KvTypeCollisionError` if the
+ * existing row's `value_type` is not 'integer' — the HTTP layer maps that to
+ * 409.
+ */
+export function incrKv(namespace: string, key: string, by: number): KvEntry {
+  if (!Number.isInteger(by) || !Number.isSafeInteger(by)) {
+    throw new Error("INCR `by` must be a JS-safe integer");
+  }
+  const database = getDb();
+  return database.transaction((): KvEntry => {
+    const existing = database
+      .prepare<KvRow, [string, string]>(
+        `SELECT namespace, key, value, value_type, expires_at, created_at, updated_at
+           FROM kv_entries WHERE namespace = ? AND key = ?`,
+      )
+      .get(namespace, key);
+
+    const now = Date.now();
+    const expired =
+      existing?.expires_at !== null &&
+      existing !== null &&
+      existing.expires_at !== null &&
+      existing.expires_at <= now;
+
+    if (!existing || expired) {
+      // Insert (or replace if expired). `upsertKv` re-enters the prepared
+      // statement cache cheaply; inlining keeps this in one transaction.
+      const row = database
+        .prepare<KvRow, [string, string, string, number | null, number, number]>(
+          `INSERT INTO kv_entries (namespace, key, value, value_type, expires_at, created_at, updated_at)
+             VALUES (?, ?, ?, 'integer', ?, ?, ?)
+           ON CONFLICT(namespace, key) DO UPDATE SET
+             value = excluded.value,
+             value_type = excluded.value_type,
+             expires_at = excluded.expires_at,
+             updated_at = excluded.updated_at
+           RETURNING namespace, key, value, value_type, expires_at, created_at, updated_at`,
+        )
+        .get(namespace, key, String(by), null, now, now);
+      if (!row) throw new Error("Failed to insert kv entry on INCR");
+      return decodeKvRow(row);
+    }
+
+    if (existing.value_type !== "integer") {
+      throw new KvTypeCollisionError(existing.value_type);
+    }
+
+    const current = Number(existing.value);
+    if (!Number.isSafeInteger(current)) {
+      throw new Error("Stored integer KV value is not a JS-safe integer");
+    }
+    const next = current + by;
+    if (!Number.isSafeInteger(next)) {
+      throw new Error("INCR would overflow JS-safe integer range");
+    }
+
+    const row = database
+      .prepare<KvRow, [string, number, string, string]>(
+        `UPDATE kv_entries SET value = ?, updated_at = ?
+           WHERE namespace = ? AND key = ?
+         RETURNING namespace, key, value, value_type, expires_at, created_at, updated_at`,
+      )
+      .get(String(next), now, namespace, key);
+    if (!row) throw new Error("Failed to update kv entry on INCR");
+    return decodeKvRow(row);
+  })();
+}
+
+/**
+ * List entries in a namespace, optionally filtered by prefix. Expired rows
+ * are filtered out by the SELECT (no inline DELETE — listing should be a
+ * stable cursor; sweeping happens on point-reads instead).
+ *
+ * `limit` is capped by the caller (HTTP enforces ≤1000); helper does no extra
+ * bounds-check beyond what SQL accepts.
+ */
+export function listKv(
+  namespace: string,
+  opts: { prefix?: string; limit: number; offset: number },
+): KvEntry[] {
+  const now = Date.now();
+  if (opts.prefix !== undefined && opts.prefix.length > 0) {
+    // LIKE-escape `\` `%` `_` so a user-supplied prefix can't run wildcards.
+    const escaped = opts.prefix.replace(/[\\%_]/g, "\\$&");
+    const rows = getDb()
+      .prepare<KvRow, [string, number, string, number, number]>(
+        `SELECT namespace, key, value, value_type, expires_at, created_at, updated_at
+           FROM kv_entries
+          WHERE namespace = ?
+            AND (expires_at IS NULL OR expires_at > ?)
+            AND key LIKE ? ESCAPE '\\'
+          ORDER BY key
+          LIMIT ? OFFSET ?`,
+      )
+      .all(namespace, now, `${escaped}%`, opts.limit, opts.offset);
+    return rows.map(decodeKvRow);
+  }
+  const rows = getDb()
+    .prepare<KvRow, [string, number, number, number]>(
+      `SELECT namespace, key, value, value_type, expires_at, created_at, updated_at
+         FROM kv_entries
+        WHERE namespace = ?
+          AND (expires_at IS NULL OR expires_at > ?)
+        ORDER BY key
+        LIMIT ? OFFSET ?`,
+    )
+    .all(namespace, now, opts.limit, opts.offset);
+  return rows.map(decodeKvRow);
+}
+
+/**
+ * Count entries in a namespace (optionally with a prefix filter). Expired
+ * rows are excluded — same predicate as `listKv`.
+ */
+export function countKv(namespace: string, opts: { prefix?: string }): number {
+  const now = Date.now();
+  if (opts.prefix !== undefined && opts.prefix.length > 0) {
+    const escaped = opts.prefix.replace(/[\\%_]/g, "\\$&");
+    const row = getDb()
+      .prepare<{ n: number }, [string, number, string]>(
+        `SELECT COUNT(*) AS n FROM kv_entries
+          WHERE namespace = ?
+            AND (expires_at IS NULL OR expires_at > ?)
+            AND key LIKE ? ESCAPE '\\'`,
+      )
+      .get(namespace, now, `${escaped}%`);
+    return row?.n ?? 0;
+  }
+  const row = getDb()
+    .prepare<{ n: number }, [string, number]>(
+      `SELECT COUNT(*) AS n FROM kv_entries
+        WHERE namespace = ?
+          AND (expires_at IS NULL OR expires_at > ?)`,
+    )
+    .get(namespace, now);
+  return row?.n ?? 0;
+}

package/src/be/migrations/061_kv_store.sql

@@ -0,0 +1,34 @@
+-- KV store: one table, namespaced. Namespace mirrors `agent_tasks.contextKey`
+-- (task:slack:..., task:trackers:..., task:agent:..., task:page:..., etc.)
+-- so the same string used to find sibling tasks for a Slack thread / PR /
+-- Linear issue also indexes KV state for that entity.
+--
+-- value_type:
+--   'json'    — `value` is the JSON-encoded payload (default; arbitrary shape).
+--   'string'  — `value` is the raw UTF-8 string verbatim.
+--   'integer' — `value` is the decimal-string form of a JS-safe integer.
+--               INCR uses this column; mixing with 'json'/'string' returns 409.
+--
+-- expires_at:
+--   Unix-ms (matches `unixepoch('subsec') * 1000`). NULL means never expires.
+--   Lazy expire on read: getKv DELETEs single expired rows; listKv filters in
+--   the SELECT but does not delete (keeps cursors stable). No background sweep.
+--
+-- WITHOUT ROWID: every read is by full PK (namespace, key); the rowid -> btree
+-- hop is wasted.
+
+CREATE TABLE IF NOT EXISTS kv_entries (
+  namespace   TEXT NOT NULL,
+  key         TEXT NOT NULL,
+  value       TEXT NOT NULL,
+  value_type  TEXT NOT NULL DEFAULT 'json'
+                CHECK (value_type IN ('json','string','integer')),
+  expires_at  INTEGER,
+  created_at  INTEGER NOT NULL DEFAULT (CAST(unixepoch('subsec') * 1000 AS INTEGER)),
+  updated_at  INTEGER NOT NULL DEFAULT (CAST(unixepoch('subsec') * 1000 AS INTEGER)),
+  PRIMARY KEY (namespace, key)
+) WITHOUT ROWID;
+
+CREATE INDEX IF NOT EXISTS idx_kv_expires
+  ON kv_entries(expires_at)
+  WHERE expires_at IS NOT NULL;

package/src/be/migrations/062_pages_view_count.sql

@@ -0,0 +1,9 @@
+-- Adds a per-page view counter to the `pages` table. Bumped on every
+-- successful 200 from `GET /p/:id` (HTML inline serve) and `GET /p/:id.json`
+-- (JSON metadata fetch). 302/401/403/404 responses do NOT bump. No
+-- per-viewer dedup — Taras explicitly wanted a "super simple counter field".
+--
+-- Bump path: src/http/pages-public.ts → bumpViewCount() → incrementPageViewCount()
+-- in src/be/db.ts. Wrapped in try/catch so analytics never breaks page serving.
+
+ALTER TABLE pages ADD COLUMN view_count INTEGER NOT NULL DEFAULT 0;

package/src/commands/provider-credentials.ts

@@ -2,7 +2,7 @@
  * Provider-agnostic credential check dispatcher (WORKER-ONLY).
  *
  * Lives in `src/commands/` because the predicates value-import worker-harness
- * SDKs (e.g. `@mariozechner/pi-coding-agent` via `pi-mono-adapter.ts`) that
+ * SDKs (e.g. `@earendil-works/pi-coding-agent` via `pi-mono-adapter.ts`) that
  * have module-load side effects. Importing this file from any module
  * reachable from `src/http.ts` would drag those SDKs into the bun-compiled
  * API binary — which is exactly the bug PR #452 hit at `/usr/local/bin/`.

package/src/http/index.ts

@@ -31,6 +31,7 @@ import { handleEvents } from "./events";
 import { handleHeartbeat } from "./heartbeat";
 import { handleInboxState } from "./inbox-state";
 import { handleIntegrations } from "./integrations";
+import { handleKv } from "./kv";
 import { handleMcp } from "./mcp";
 import { handleMcpOAuth, startMcpOAuthPendingGc, stopMcpOAuthPendingGc } from "./mcp-oauth";
 import { handleMcpServers } from "./mcp-servers";
@@ -142,6 +143,7 @@ const httpServer = createHttpServer(async (req, res) => {
     () => handleWorkflowEvents(req, res, pathSegments, queryParams),
     () => handleApprovalRequests(req, res, pathSegments, queryParams),
     () => handleConfig(req, res, pathSegments, queryParams),
+    () => handleKv(req, res, pathSegments, queryParams),
     () => handleIntegrations(req, res, pathSegments),
     () => handlePromptTemplates(req, res, pathSegments, queryParams),
     () => handleDbQuery(req, res, pathSegments, queryParams),