@zackbart/connecta 0.28.1 → 0.29.0

package/examples/worker/src/d1-activity-row.ts

@@ -1,155 +0,0 @@
-// Keep this pure mapping module dependency-free so the repository's tests can
-// exercise the example before the package's dist/ entrypoint has been built.
-// The public adapter in d1-activity.ts remains checked against ActivityStore.
-export interface ActivityEvent {
-  schemaVersion: 1;
-  id: string;
-  occurredAt: string;
-  requestId: string;
-  actor: {
-    kind: string;
-    id?: string;
-    namespace?: string;
-  };
-  connectorId: string;
-  toolName: string;
-  address: string;
-  source:
-    | "call_tool"
-    | "call_destructive_tool"
-    | "batch_call"
-    | "execute_code"
-    // History only: rows written before 0.28.0 removed program pauses.
-    | "resume_execution";
-  outcome:
-    | "success"
-    | "error"
-    | "timeout"
-    | "cancelled"
-    // History only, like `resume_execution` above.
-    | "paused"
-    | "approved";
-  durationMs: number;
-  attempts: number;
-  errorCode?: string;
-  friction?:
-    | "tool_not_found"
-    | "schema_retry"
-    | "destructive_reroute"
-    | "auth_required"
-    | "result_too_large";
-  /** History only: the scope an `approved` row covered, before 0.28.0. */
-  approval?: "call" | "tool";
-  serverName: string;
-  serverVersion: string;
-  deploymentId?: string;
-}
-
-/**
- * Backfill for rows written before `friction` had a column of its own. Every
- * arm must agree with the package's own `agentFrictionForCode`; the repository
- * test suite pins that, because a dashboard that groups by friction should not
- * change its answer depending on which side of a migration a row landed on.
- * Friction that never had an error code — an oversized but successful result —
- * is only recoverable from the column, which is why the column exists.
- */
-function frictionForCode(code: string | null): ActivityEvent["friction"] {
-  switch (code) {
-    case "unknown_address":
-    case "unknown_tool":
-    case "ambiguous_tool_alias":
-      return "tool_not_found";
-    case "invalid_args":
-      return "schema_retry";
-    case "destructive_tool_requires_approval":
-      return "destructive_reroute";
-    case "auth_required":
-      return "auth_required";
-    case "result_too_large":
-      return "result_too_large";
-    default:
-      return undefined;
-  }
-}
-
-export interface ActivityRow {
-  id: string;
-  occurred_at_ms: number;
-  request_id: string;
-  actor_kind: string;
-  actor_id: string | null;
-  actor_namespace: string | null;
-  connector_id: string;
-  tool_name: string;
-  source: ActivityEvent["source"];
-  outcome: ActivityEvent["outcome"];
-  duration_ms: number;
-  attempts: number;
-  error_code: string | null;
-  friction: ActivityEvent["friction"] | null;
-  /** Absent from tables created before 0.26.0; null on every row since 0.28.0. */
-  approval?: ActivityEvent["approval"] | null;
-  server_name: string;
-  server_version: string;
-  deployment_id: string | null;
-}
-
-export function activityEventToRow(
-  event: ActivityEvent,
-): ActivityRow {
-  return {
-    id: event.id,
-    occurred_at_ms: Date.parse(event.occurredAt),
-    request_id: event.requestId,
-    actor_kind: event.actor.kind,
-    actor_id: event.actor.id ?? null,
-    actor_namespace: event.actor.namespace ?? null,
-    connector_id: event.connectorId,
-    tool_name: event.toolName,
-    source: event.source,
-    outcome: event.outcome,
-    duration_ms: event.durationMs,
-    attempts: event.attempts,
-    error_code: event.errorCode ?? null,
-    // Stored beside the code rather than derived from it: a truncated result is
-    // friction on a call that succeeded, so it has no error code to derive from
-    // — and `error_code IS NOT NULL` stays an honest count of failures.
-    friction: event.friction ?? null,
-    approval: event.approval ?? null,
-    server_name: event.serverName,
-    server_version: event.serverVersion,
-    deployment_id: event.deploymentId ?? null,
-  };
-}
-
-export function activityRowToEvent(
-  row: ActivityRow,
-): ActivityEvent {
-  const friction = row.friction ?? frictionForCode(row.error_code);
-  return {
-    schemaVersion: 1,
-    id: row.id,
-    occurredAt: new Date(row.occurred_at_ms).toISOString(),
-    requestId: row.request_id,
-    actor: {
-      kind: row.actor_kind,
-      ...(row.actor_id ? { id: row.actor_id } : {}),
-      ...(row.actor_namespace ? { namespace: row.actor_namespace } : {}),
-    },
-    connectorId: row.connector_id,
-    toolName: row.tool_name,
-    address: `${row.connector_id}.${row.tool_name}`,
-    source: row.source,
-    outcome: row.outcome,
-    durationMs: row.duration_ms,
-    attempts: row.attempts,
-    ...(row.error_code ? { errorCode: row.error_code } : {}),
-    ...(friction ? { friction } : {}),
-    ...(row.approval ? { approval: row.approval } : {}),
-    serverName: row.server_name,
-    serverVersion: row.server_version,
-    ...(row.deployment_id
-      ? { deploymentId: row.deployment_id }
-      : {}),
-  };
-}

package/examples/worker/src/d1-activity.ts

@@ -1,147 +0,0 @@
-import type {
-  ActivityPage,
-  ActivityStore,
-} from "@zackbart/connecta";
-import { InvalidActivityCursorError } from "@zackbart/connecta/activity";
-import {
-  activityEventToRow,
-  activityRowToEvent,
-  type ActivityRow,
-} from "./d1-activity-row.js";
-
-interface Cursor {
-  occurredAtMs: number;
-  id: string;
-}
-
-function encodeCursor(row: ActivityRow): string {
-  return btoa(`${row.occurred_at_ms}:${row.id}`);
-}
-
-function decodeCursor(value: string): Cursor {
-  let decoded: string;
-  try {
-    decoded = atob(value);
-  } catch {
-    throw new InvalidActivityCursorError();
-  }
-  const separator = decoded.indexOf(":");
-  const occurredAtMs = Number(decoded.slice(0, separator));
-  const id = decoded.slice(separator + 1);
-  if (
-    separator < 1 ||
-    !Number.isSafeInteger(occurredAtMs) ||
-    occurredAtMs < 0 ||
-    !/^[0-9a-f-]{36}$/i.test(id)
-  ) {
-    throw new InvalidActivityCursorError();
-  }
-  return { occurredAtMs, id };
-}
-
-/** One append-only row per completed downstream call; no arguments or results. */
-export function d1ActivityStore(db: D1Database): ActivityStore {
-  return {
-    async record(event) {
-      const row = activityEventToRow(event);
-      await db
-        .prepare(
-          `INSERT INTO tool_call_activity (
-            id, occurred_at_ms, request_id, actor_kind, actor_id,
-            actor_namespace,
-            connector_id, tool_name, source, outcome, duration_ms, attempts,
-            error_code, friction, approval, server_name, server_version,
-            deployment_id
-          ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-        )
-        .bind(
-          row.id,
-          row.occurred_at_ms,
-          row.request_id,
-          row.actor_kind,
-          row.actor_id,
-          row.actor_namespace,
-          row.connector_id,
-          row.tool_name,
-          row.source,
-          row.outcome,
-          row.duration_ms,
-          row.attempts,
-          row.error_code,
-          row.friction ?? null,
-          row.approval ?? null,
-          row.server_name,
-          row.server_version,
-          row.deployment_id,
-        )
-        .run();
-    },
-
-    async list({ cursor, limit }): Promise<ActivityPage> {
-      const boundedLimit = Math.min(100, Math.max(1, Math.trunc(limit)));
-      const pageSize = boundedLimit + 1;
-      const position = cursor ? decodeCursor(cursor) : undefined;
-      const statement = position
-        ? db
-            .prepare(
-              `SELECT * FROM tool_call_activity
-               WHERE occurred_at_ms < ?
-                  OR (occurred_at_ms = ? AND id < ?)
-               ORDER BY occurred_at_ms DESC, id DESC
-               LIMIT ?`,
-            )
-            .bind(
-              position.occurredAtMs,
-              position.occurredAtMs,
-              position.id,
-              pageSize,
-            )
-        : db
-            .prepare(
-              `SELECT * FROM tool_call_activity
-               ORDER BY occurred_at_ms DESC, id DESC
-               LIMIT ?`,
-            )
-            .bind(pageSize);
-      const result = await statement.all<ActivityRow>();
-      const rows = result.results ?? [];
-      const hasMore = rows.length > boundedLimit;
-      const visible = hasMore ? rows.slice(0, boundedLimit) : rows;
-      const last = visible.at(-1);
-      return {
-        events: visible.map(activityRowToEvent),
-        ...(hasMore && last ? { nextCursor: encodeCursor(last) } : {}),
-      };
-    },
-  };
-}
-
-/**
- * Daily retention pass. Each statement is capped at 5,000 rows, then repeats
- * up to a per-run ceiling so normal traffic catches up without allowing one
- * scheduled invocation to consume unbounded queries.
- */
-export async function pruneActivity(
-  db: D1Database,
-  retentionDays: number,
-  maxBatches = 20,
-): Promise<void> {
-  const cutoff = Date.now() -
-    Math.max(1, Math.trunc(retentionDays)) * 24 * 60 * 60 * 1_000;
-  const batchLimit = Math.max(1, Math.trunc(maxBatches));
-  for (let batch = 0; batch < batchLimit; batch++) {
-    const result = await db
-      .prepare(
-        `DELETE FROM tool_call_activity
-         WHERE id IN (
-           SELECT id FROM tool_call_activity
-           WHERE occurred_at_ms < ?
-           ORDER BY occurred_at_ms ASC
-           LIMIT 5000
-         )`,
-      )
-      .bind(cutoff)
-      .run();
-    if ((result.meta.changes ?? 0) < 5_000) return;
-  }
-}

package/examples/worker/src/d1-storage.ts

@@ -1,138 +0,0 @@
-import type { KVStorage } from "@zackbart/connecta";
-
-/**
- * KVStorage over a D1 database, with the atomic `compareAndSet` that Workers
- * KV cannot offer. Apply the `connecta_kv` schema in README.md § "Strongly
- * consistent storage" before first use.
- *
- * Every compare-and-set is a single SQL statement. D1 runs one database's
- * statements one at a time against its primary, so the comparison and the
- * write cannot interleave with another request's: of fifty concurrent claims
- * on an absent key, exactly one changes a row.
- *
- * Expiry is judged by the Worker's clock at each call, the same `Date.now()`
- * the core uses. An expired row reads as absent immediately and is removed
- * physically by later writes, a bounded batch at a time, so no request starts
- * a background job and no cron is required.
- */
-export function d1Storage(db: D1Database): KVStorage {
-  // Every statement that tests liveness binds the current time as ?2.
-  const live = "(expires_at_ms IS NULL OR expires_at_ms > ?2)";
-  const expiresAt = (now: number, ttlSeconds?: number): number | null => {
-    if (ttlSeconds !== undefined && !Number.isFinite(ttlSeconds)) {
-      throw new RangeError("ttlSeconds must produce a finite expiration timestamp");
-    }
-    if (!ttlSeconds) return null;
-    const expiry = now + ttlSeconds * 1000;
-    if (!Number.isFinite(expiry)) {
-      throw new RangeError("ttlSeconds must produce a finite expiration timestamp");
-    }
-    return expiry;
-  };
-  const changed = (result: D1Result) => result.meta.changes > 0;
-  return {
-    async get(key) {
-      const row = await db
-        .prepare(`SELECT value FROM connecta_kv WHERE key = ?1 AND ${live}`)
-        .bind(key, Date.now())
-        .first<{ value: string }>();
-      return row?.value ?? null;
-    },
-    async set(key, value, opts) {
-      const now = Date.now();
-      const expiry = expiresAt(now, opts?.ttlSeconds);
-      await db.batch([
-        db
-          .prepare(
-            `DELETE FROM connecta_kv WHERE key IN (
-              SELECT key FROM connecta_kv WHERE expires_at_ms <= ?1 LIMIT 16
-            )`,
-          )
-          .bind(now),
-        db
-          .prepare(
-            `INSERT INTO connecta_kv (key, value, expires_at_ms)
-             VALUES (?1, ?2, ?3)
-             ON CONFLICT (key) DO UPDATE SET
-               value = excluded.value, expires_at_ms = excluded.expires_at_ms`,
-          )
-          .bind(key, value, expiry),
-      ]);
-    },
-    async delete(key) {
-      await db.prepare("DELETE FROM connecta_kv WHERE key = ?1").bind(key).run();
-    },
-    async list(prefix) {
-      const { results } = await db
-        .prepare(
-          `SELECT key FROM connecta_kv
-           WHERE key >= ?1 AND substr(CAST(key AS BLOB), 1, length(CAST(?1 AS BLOB))) = CAST(?1 AS BLOB) AND ${live}`,
-        )
-        .bind(prefix, Date.now())
-        .all<{ key: string }>();
-      // Sort in JavaScript: SQLite orders UTF-8 bytes, the contract orders
-      // the UTF-16 code units every other adapter sorts by.
-      return results.map((row) => row.key).sort();
-    },
-    async compareAndSet(key, expected, next, opts) {
-      const now = Date.now();
-      if (next === null && expected === null) {
-        // Nothing to write; the claim holds exactly when no live row exists.
-        const row = await db
-          .prepare(`SELECT 1 AS present FROM connecta_kv WHERE key = ?1 AND ${live}`)
-          .bind(key, now)
-          .first();
-        return row === null;
-      }
-      if (next === null) {
-        return changed(
-          await db
-            .prepare(
-              `DELETE FROM connecta_kv WHERE key = ?1 AND ${live} AND value = ?3`,
-            )
-            .bind(key, now, expected)
-            .run(),
-        );
-      }
-      let expiry: number | null;
-      try {
-        expiry = expiresAt(now, opts?.ttlSeconds);
-      } catch (error) {
-        // Invalid write options do not change a failed comparison's result.
-        // Ordinary claims still use one atomic statement without this read.
-        const current = await db
-          .prepare(`SELECT value FROM connecta_kv WHERE key = ?1 AND ${live}`)
-          .bind(key, now)
-          .first<{ value: string }>();
-        if ((current?.value ?? null) !== expected) return false;
-        throw error;
-      }
-      if (expected === null) {
-        // Insert, or take over a row that has expired. A live row makes the
-        // upsert's WHERE false, so nothing changes and the claim is refused.
-        return changed(
-          await db
-            .prepare(
-              `INSERT INTO connecta_kv (key, value, expires_at_ms)
-               VALUES (?1, ?3, ?4)
-               ON CONFLICT (key) DO UPDATE SET
-                 value = excluded.value, expires_at_ms = excluded.expires_at_ms
-               WHERE connecta_kv.expires_at_ms IS NOT NULL
-                 AND connecta_kv.expires_at_ms <= ?2`,
-            )
-            .bind(key, now, next, expiry)
-            .run(),
-        );
-      }
-      return changed(
-        await db
-          .prepare(
-            `UPDATE connecta_kv SET value = ?4, expires_at_ms = ?5
-             WHERE key = ?1 AND ${live} AND value = ?3`,
-          )
-          .bind(key, now, expected, next, expiry)
-          .run(),
-      );
-    },
-  };
-}

package/examples/worker/src/r2-artifact-blobs.ts

@@ -1,29 +0,0 @@
-import type { ArtifactBlobStore } from "@zackbart/connecta/artifacts";
-
-/**
- * Artifact bodies — page sources, data documents, refresh programs — in an R2
- * bucket, beside a D1-backed `kvArtifactStore` that keeps the heads, versions,
- * and runs. Optional: without it, bodies live in D1 rows, which the default
- * limits keep well under D1's row size. Use it once pages or documents grow,
- * or to keep large bodies out of the database a backup copies.
- *
- * Keys are content addresses, so writing one twice writes the same bytes, and
- * nothing here ever deletes one: versions are immutable, and a rollback points
- * back at an old body rather than copying it.
- */
-export function r2ArtifactBlobs(
-  bucket: R2Bucket,
-  prefix = "artifacts/blobs/",
-): ArtifactBlobStore {
-  return {
-    async put(key, body) {
-      await bucket.put(`${prefix}${key}`, body, {
-        httpMetadata: { contentType: "text/plain; charset=utf-8" },
-      });
-    },
-    async get(key) {
-      const object = await bucket.get(`${prefix}${key}`);
-      return object ? object.text() : null;
-    },
-  };
-}

package/templates/node/src/file-activity.ts

@@ -1,182 +0,0 @@
-/**
- * Payload-free tool activity, kept in a JSON-lines file beside the state file.
- *
- * Deployment-owned on purpose: Connecta ships the `ActivityStore` contract, not
- * a backend, because retention is a decision only the operator can make. This
- * is the Node counterpart of the Worker example's D1 store, sized for one
- * container rather than a fleet — a write appends one line, and the log is
- * bounded by a count of events instead of by age, so nothing has to be
- * scheduled.
- *
- * Nothing wires it by default. `src/index.ts` carries the commented lines that
- * turn it on; README.md § "Turn on the operator surface" explains why they are
- * commented.
- */
-import {
-  appendFileSync,
-  chmodSync,
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  renameSync,
-  writeFileSync,
-} from "node:fs";
-import { dirname } from "node:path";
-import type {
-  ActivityPage,
-  ActivityStore,
-  ToolCallActivityEvent,
-} from "@zackbart/connecta";
-import { InvalidActivityCursorError } from "@zackbart/connecta/activity";
-
-/**
- * Events allowed past `maxEvents` before the log is rewritten. Trimming on the
- * write that first crosses the ceiling would rewrite the whole file on every
- * call from then on; this pays that cost once per slack window instead.
- */
-const COMPACTION_SLACK = 500;
-
-export interface FileActivityOptions {
-  /** Newest events retained after a compaction. Default 5,000. */
-  maxEvents?: number;
-}
-
-/** Newest first, with the id breaking ties inside a millisecond. */
-function newestFirst(
-  a: ToolCallActivityEvent,
-  b: ToolCallActivityEvent,
-): number {
-  const byTime = Date.parse(b.occurredAt) - Date.parse(a.occurredAt);
-  return byTime !== 0 ? byTime : b.id.localeCompare(a.id);
-}
-
-function encodeCursor(event: ToolCallActivityEvent): string {
-  return Buffer.from(`${Date.parse(event.occurredAt)}:${event.id}`).toString(
-    "base64",
-  );
-}
-
-function decodeCursor(value: string): { occurredAtMs: number; id: string } {
-  const decoded = Buffer.from(value, "base64").toString("utf8");
-  const separator = decoded.indexOf(":");
-  const occurredAtMs = Number(decoded.slice(0, separator));
-  const id = decoded.slice(separator + 1);
-  if (separator < 1 || !Number.isSafeInteger(occurredAtMs) || !id) {
-    throw new InvalidActivityCursorError();
-  }
-  return { occurredAtMs, id };
-}
-
-/** Strictly older than the cursor position, in the order above. */
-function isBefore(
-  event: ToolCallActivityEvent,
-  position: { occurredAtMs: number; id: string },
-): boolean {
-  const occurredAtMs = Date.parse(event.occurredAt);
-  if (occurredAtMs !== position.occurredAtMs) {
-    return occurredAtMs < position.occurredAtMs;
-  }
-  return event.id.localeCompare(position.id) < 0;
-}
-
-/**
- * One append-only record per completed downstream call. Events carry no
- * arguments, results, generated code, or raw error messages — the store never
- * has a payload to leak. Writes are best-effort by contract: a throw here is
- * logged by Connecta and never reaches the tool result.
- */
-export function fileActivityStore(
-  path: string,
-  opts: FileActivityOptions = {},
-): ActivityStore {
-  const maxEvents = Math.max(1, Math.trunc(opts.maxEvents ?? 5_000));
-  // Activity records who called what, so it is owner-only like the state file.
-  const tighten = () => {
-    try {
-      chmodSync(path, 0o600);
-    } catch {
-      // Non-POSIX filesystem or a race on the file — leave the mode as-is.
-    }
-  };
-  let events: ToolCallActivityEvent[] = [];
-  // Damage found at load that the file itself still carries: a dropped line, or
-  // a last line with no newline after it. Both are repaired by rewriting the
-  // file from what parsed, because the alternative is appending onto a
-  // fragment and losing the *next* event too — one that never had anything
-  // wrong with it.
-  let repairNeeded = false;
-  if (existsSync(path)) {
-    tighten();
-    // A half-written trailing line is the normal cost of an append log, and
-    // one unreadable line is not a reason to lose the history above it. Unlike
-    // the state file there is nothing irreplaceable here — this is a record of
-    // calls that already happened — so damaged lines are dropped, loudly.
-    const raw = readFileSync(path, "utf8");
-    const lines = raw.split("\n").filter(Boolean);
-    let dropped = 0;
-    for (const line of lines) {
-      try {
-        events.push(JSON.parse(line) as ToolCallActivityEvent);
-      } catch {
-        dropped += 1;
-      }
-    }
-    if (dropped > 0) {
-      console.error(
-        `[connecta] activity log ${path}: dropped ${dropped} unreadable ` +
-          `line(s) of ${lines.length}.`,
-      );
-    }
-    repairNeeded = dropped > 0 || (raw.length > 0 && !raw.endsWith("\n"));
-  }
-  const ensureDirectory = () => {
-    const dir = dirname(path);
-    if (dir) mkdirSync(dir, { recursive: true, mode: 0o700 });
-  };
-  const compact = () => {
-    events = [...events].sort(newestFirst).slice(0, maxEvents);
-    ensureDirectory();
-    const tmp = `${path}.tmp`;
-    // 0o600 on the temp file; the rename preserves it, so the live log is
-    // never briefly world-readable.
-    writeFileSync(
-      tmp,
-      events.map((event) => `${JSON.stringify(event)}\n`).join(""),
-      { mode: 0o600 },
-    );
-    renameSync(tmp, path);
-    tighten();
-  };
-  // Repair before the first append rather than at the next restart: the
-  // fragment is on disk until something rewrites the file, and an append onto
-  // it corrupts a good event into an unreadable line.
-  if (repairNeeded) compact();
-  return {
-    record(event) {
-      events.push(event);
-      if (events.length > maxEvents + COMPACTION_SLACK) {
-        compact();
-        return;
-      }
-      ensureDirectory();
-      appendFileSync(path, `${JSON.stringify(event)}\n`, { mode: 0o600 });
-      tighten();
-    },
-
-    async list({ cursor, limit }): Promise<ActivityPage> {
-      const boundedLimit = Math.min(100, Math.max(1, Math.trunc(limit)));
-      const position = cursor ? decodeCursor(cursor) : undefined;
-      const ordered = [...events]
-        .sort(newestFirst)
-        .filter((event) => !position || isBefore(event, position));
-      const visible = ordered.slice(0, boundedLimit);
-      const last = visible.at(-1);
-      return {
-        events: visible,
-        ...(ordered.length > visible.length && last
-          ? { nextCursor: encodeCursor(last) }
-          : {}),
-      };
-    },
-  };
-}