@aghents/gateway 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,198 @@
+import { Result } from 'neverthrow';
+import { z } from 'zod';
+import { PulseServiceClient, PulseGame, GameStore, PulseError } from '@aghents/pulse';
+export { SCHEDULER_CADENCE_MS } from '@aghents/pulse';
+
+/**
+ * The persona contract. Personas decide from a seat's View ONLY, never GameState; no wall clock
+ * and no global RNG anywhere in this package: `nowMs`, `rng` and `fraction` are parameters.
+ */
+
+type GatewayError = {
+    code: "llm" | "invalid_slug" | "handle_taken" | "db";
+    message: string;
+};
+interface PersonaTiming {
+    /** Earliest action time as a fraction of the open window (0..1). */
+    minFraction: number;
+    /** Latest action time as a fraction of the open window (0..1). */
+    maxFraction: number;
+}
+/**
+ * What a persona decided, and (when it differs from the persona's own tier/model) what produced
+ * it: an llm persona's heuristic fallback discloses as heuristic, never as the model it skipped.
+ */
+type Decision<E> = {
+    events: E[];
+    produced?: {
+        tier: "heuristic" | "llm";
+        model: string;
+    };
+};
+interface Persona<V, E> {
+    personaId: string;
+    tier: "heuristic" | "llm";
+    model: string;
+    timing: PersonaTiming;
+    decide(input: {
+        view: V;
+        rng: () => number;
+        fraction: number;
+    }): Promise<Decision<E>>;
+}
+declare const LLM_MAX_TOKENS = 400;
+/**
+ * An llm-tier persona: prompt from the view, complete, parse the text into events. A completer
+ * failure rejects, and the scheduler turns that into a `skipped` seat.
+ */
+declare function llmPersona<V, E>(opts: {
+    personaId: string;
+    model: string;
+    completer: Completer;
+    prompt: (view: V) => {
+        system: string;
+        user: string;
+    };
+    parse: (text: string, view: V) => E[];
+    timing?: PersonaTiming;
+    /**
+     * Used when the completer errs or `parse` yields nothing, so an llm persona backed by a
+     * heuristic never spends a second call on the same pulse. Without it the scheduler marks the
+     * seat skipped and asks again next tick.
+     */
+    fallback?: (input: {
+        view: V;
+        rng: () => number;
+        fraction: number;
+    }) => E[];
+}): Persona<V, E>;
+
+interface Completer {
+    complete(input: {
+        system: string;
+        user: string;
+        maxTokens: number;
+    }): Promise<Result<string, GatewayError>>;
+}
+
+declare const schema: z.ZodObject<{
+    ANTHROPIC_API_KEY: z.ZodString;
+    AGHENTS_LLM_MODEL: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    ANTHROPIC_API_KEY: string;
+    AGHENTS_LLM_MODEL: string;
+}, {
+    ANTHROPIC_API_KEY: string;
+    AGHENTS_LLM_MODEL?: string | undefined;
+}>;
+type LlmEnv = z.infer<typeof schema>;
+declare function readLlmEnv(raw: Record<string, string | undefined>): LlmEnv;
+
+/** One call's worst case: the SDK timeout times the attempts (one retry). The scheduler reserves this much of its deadline before an llm decision. */
+declare const LLM_TIMEOUT_MS = 20000;
+declare const LLM_MAX_RETRIES = 1;
+declare const LLM_WORST_CASE_MS: number;
+/** Pad for the awaits between the reserve check and the call itself (the budget spend). */
+declare const LLM_PREFLIGHT_MS = 2000;
+declare class AnthropicCompleter implements Completer {
+    private readonly client;
+    private readonly model;
+    constructor(opts: {
+        env: LlmEnv;
+        fetch?: typeof globalThis.fetch;
+    });
+    complete(input: {
+        system: string;
+        user: string;
+        maxTokens: number;
+    }): Promise<Result<string, GatewayError>>;
+}
+
+/** Scripted replies for tests, consumed in order; records every call. */
+declare class FakeCompleter implements Completer {
+    private readonly replies;
+    readonly calls: {
+        system: string;
+        user: string;
+        maxTokens: number;
+    }[];
+    constructor(replies: string[]);
+    complete(input: {
+        system: string;
+        user: string;
+        maxTokens: number;
+    }): Promise<Result<string, GatewayError>>;
+}
+
+/**
+ * Mint an identity.profiles row for a persona. profiles.id references auth.users, so the persona
+ * gets an auth user first: no password and an .invalid address, so nothing can ever sign in as
+ * it. Idempotent: an existing persona profile row wins; an existing auth user without one is
+ * looked up by email and reused. The `persona-` handle namespace is reserved to kind='persona'
+ * (0004_persona_handles.sql), so a human row under this handle can only predate 0004; it is
+ * never returned as the persona.
+ */
+declare function mintPersonaProfile(serviceClient: PulseServiceClient, input: {
+    slug: string;
+    displayName: string;
+}): Promise<Result<{
+    id: string;
+}, GatewayError>>;
+
+type Log = (message: string, context: Record<string, unknown>) => void;
+
+/**
+ * What must remain of a window after a persona's due time, per tier: one scheduler cadence
+ * (so a cron tick lands after it) plus, for an llm seat, the worst case of its call (so the
+ * tick that finds it due can still afford the decision before the window closes).
+ */
+declare const LLM_RESERVE_MS: number;
+declare const dueReserveMs: (tier: Persona<unknown, unknown>["tier"]) => number;
+/** The shortest window in which every tier can still act: cadence + the llm worst case. */
+declare const MIN_WINDOW_MS: number;
+/**
+ * When a persona is due: its offset into the window, clamped so `dueReserveMs(tier)` remains
+ * before the window ends. Otherwise an offset in the window's tail can fall between two cron
+ * ticks, the next of which advances the phase (or refuses the llm reserve) before the persona
+ * acts. A window shorter than the reserve is due at its start.
+ */
+declare function dueAtMs(windowStartMs: number, windowMs: number, offsetMs: number, tier?: Persona<unknown, unknown>["tier"]): number;
+/**
+ * One scheduler pass over one game: catch the clock up, then let every due persona act once per
+ * phase, in both the open and the lock window (which events each phase takes is the game's
+ * `advance`: Circle claims in open and votes in lock). "Acted this phase" is read off the store:
+ * the persona ids on events after the last system (clock) event. Idempotent: a second tick in the
+ * same phase acts nobody. A game-level failure (the clock could not be caught up, or the record
+ * or log could not be read afterwards) is an err with the pulse code, logged, so a pass never
+ * reports an outage as an empty success. `nowMs` is the pass start (offsets, catchUp); `now()`
+ * is the live clock for the pre-decide budget, the post-decide window check and the submit
+ * time (pure: callers inject it, tests pass a fake). With a `deadline`, due seats not reached
+ * before `now() >= deadline.atMs` are returned as `deferred` (the next tick asks them).
+ */
+type TickResult = {
+    acted: string[];
+    skipped: string[];
+    deferred: string[];
+};
+declare function tick<S, E, V>(input: {
+    game: PulseGame<S, E, V>;
+    store: GameStore<E>;
+    personas: Map<string, Persona<V, E>>;
+    gameId: string;
+    nowMs: number;
+    now: () => number;
+    deadline?: {
+        atMs: number;
+    };
+    log?: Log;
+}): Promise<Result<TickResult, PulseError>>;
+
+/**
+ * Millisecond offsets within a pulse window at which a persona acts. Ported unchanged from
+ * Circle packages/personas/src/timing.ts. Pure: the scheduler owns wall-clock time.
+ */
+declare function actionOffsets(count: number, windowMs: number, profile: {
+    timing: PersonaTiming;
+}, rng: () => number): number[];
+
+export { AnthropicCompleter, type Completer, type Decision, FakeCompleter, type GatewayError, LLM_MAX_RETRIES, LLM_MAX_TOKENS, LLM_PREFLIGHT_MS, LLM_RESERVE_MS, LLM_TIMEOUT_MS, LLM_WORST_CASE_MS, type LlmEnv, type Log, MIN_WINDOW_MS, type Persona, type PersonaTiming, type TickResult, actionOffsets, dueAtMs, dueReserveMs, llmPersona, mintPersonaProfile, readLlmEnv, tick };

package/dist/index.js

@@ -0,0 +1,305 @@
+// src/completer.anthropic.ts
+import Anthropic from "@anthropic-ai/sdk";
+import { err, ok } from "neverthrow";
+
+// src/persona.ts
+var LLM_MAX_TOKENS = 400;
+var DEFAULT_TIMING = { minFraction: 0.1, maxFraction: 0.8 };
+function llmPersona(opts) {
+  return {
+    personaId: opts.personaId,
+    tier: "llm",
+    model: opts.model,
+    timing: opts.timing ?? DEFAULT_TIMING,
+    async decide(input) {
+      const { system, user } = opts.prompt(input.view);
+      const r = await opts.completer.complete({ system, user, maxTokens: LLM_MAX_TOKENS });
+      let events = [];
+      if (r.isOk()) {
+        try {
+          events = opts.parse(r.value, input.view);
+        } catch {
+          events = [];
+        }
+      }
+      if (events.length > 0) return { events };
+      if (opts.fallback) {
+        return {
+          events: opts.fallback(input),
+          produced: { tier: "heuristic", model: "heuristic:fallback" }
+        };
+      }
+      if (r.isErr()) throw new Error(`${r.error.code}: ${r.error.message}`);
+      return { events: [] };
+    }
+  };
+}
+
+// src/completer.anthropic.ts
+var LLM_TIMEOUT_MS = 2e4;
+var LLM_MAX_RETRIES = 1;
+var LLM_WORST_CASE_MS = LLM_TIMEOUT_MS * (LLM_MAX_RETRIES + 1);
+var LLM_PREFLIGHT_MS = 2e3;
+var AnthropicCompleter = class {
+  client;
+  model;
+  constructor(opts) {
+    this.model = opts.env.AGHENTS_LLM_MODEL;
+    this.client = new Anthropic({
+      apiKey: opts.env.ANTHROPIC_API_KEY,
+      timeout: LLM_TIMEOUT_MS,
+      maxRetries: LLM_MAX_RETRIES,
+      ...opts.fetch ? { fetch: opts.fetch } : {}
+    });
+  }
+  async complete(input) {
+    try {
+      const res = await this.client.messages.create({
+        model: this.model,
+        max_tokens: Math.min(input.maxTokens, LLM_MAX_TOKENS),
+        system: input.system,
+        messages: [{ role: "user", content: input.user }]
+      });
+      const text = res.content.filter((b) => b.type === "text").map((b) => b.text).join("");
+      return ok(text);
+    } catch (e) {
+      return err({ code: "llm", message: e instanceof Error ? e.message : String(e) });
+    }
+  }
+};
+
+// src/completer.fake.ts
+import { err as err2, ok as ok2 } from "neverthrow";
+var FakeCompleter = class {
+  constructor(replies) {
+    this.replies = replies;
+  }
+  replies;
+  calls = [];
+  async complete(input) {
+    this.calls.push(input);
+    const reply = this.replies.shift();
+    return reply === void 0 ? err2({ code: "llm", message: `no scripted reply for call ${this.calls.length}` }) : ok2(reply);
+  }
+};
+
+// src/env.ts
+import { z } from "zod";
+var schema = z.object({
+  ANTHROPIC_API_KEY: z.string().min(1),
+  AGHENTS_LLM_MODEL: z.string().min(1).default("claude-sonnet-5")
+});
+function readLlmEnv(raw) {
+  return schema.parse(raw);
+}
+
+// src/profile.ts
+import { err as err3, ok as ok3 } from "neverthrow";
+import { z as z2 } from "zod";
+var slug = z2.string().regex(/^[a-z0-9-]{1,16}$/);
+var personaEmail = (s) => `persona-${s}@personas.aghents.invalid`;
+async function mintPersonaProfile(serviceClient, input) {
+  const parsed = slug.safeParse(input.slug);
+  if (!parsed.success) {
+    return err3({ code: "invalid_slug", message: "slug must match ^[a-z0-9-]{1,16}$" });
+  }
+  const handle = `persona-${parsed.data}`;
+  const identity = serviceClient.schema("identity");
+  const existing = await identity.from("profiles").select("id, kind").eq("handle", handle).maybeSingle();
+  if (existing.error) return err3({ code: "db", message: existing.error.message });
+  if (existing.data?.kind === "persona") return ok3({ id: existing.data.id });
+  if (existing.data) {
+    return err3({ code: "handle_taken", message: `${handle} belongs to a ${existing.data.kind}` });
+  }
+  const user = await userId(serviceClient, personaEmail(parsed.data));
+  if (user.isErr()) return err3(user.error);
+  const { error } = await identity.from("profiles").upsert(
+    { id: user.value, handle, display_name: input.displayName, kind: "persona" },
+    { onConflict: "id" }
+  );
+  return error ? err3({ code: "db", message: error.message }) : ok3({ id: user.value });
+}
+async function userId(client, email) {
+  const created = await client.auth.admin.createUser({
+    email,
+    email_confirm: true,
+    user_metadata: { kind: "persona" },
+    app_metadata: { kind: "persona" }
+  });
+  if (!created.error) return ok3(created.data.user.id);
+  if (created.error.code !== "email_exists") {
+    return err3({ code: "db", message: created.error.message });
+  }
+  for (let page = 1; ; page++) {
+    const list = await client.auth.admin.listUsers({ page, perPage: 1e3 });
+    if (list.error) return err3({ code: "db", message: list.error.message });
+    const hit = list.data.users.find((u) => u.email === email);
+    if (hit) {
+      return hit.app_metadata?.kind === "persona" ? ok3(hit.id) : err3({ code: "handle_taken", message: `${email} is a client-created account` });
+    }
+    if (list.data.users.length < 1e3) return err3({ code: "db", message: `no user ${email}` });
+  }
+}
+
+// src/scheduler.ts
+import {
+  SCHEDULER_CADENCE_MS,
+  catchUp,
+  createRng,
+  getView,
+  pulseTimes,
+  submit
+} from "@aghents/pulse";
+import { err as err4, ok as ok4 } from "neverthrow";
+
+// src/timing.ts
+function actionOffsets(count, windowMs, profile, rng) {
+  const lo = profile.timing.minFraction * windowMs;
+  const hi = profile.timing.maxFraction * windowMs;
+  return Array.from({ length: count }, () => lo + rng() * (hi - lo)).sort((a, b) => a - b);
+}
+
+// src/scheduler.ts
+var noop = () => {
+};
+var LLM_RESERVE_MS = LLM_WORST_CASE_MS + LLM_PREFLIGHT_MS;
+var dueReserveMs = (tier) => SCHEDULER_CADENCE_MS + (tier === "llm" ? LLM_RESERVE_MS : 0);
+var MIN_WINDOW_MS = dueReserveMs("llm");
+function dueAtMs(windowStartMs, windowMs, offsetMs, tier = "heuristic") {
+  const latest = Math.max(windowStartMs, windowStartMs + windowMs - dueReserveMs(tier));
+  return Math.min(windowStartMs + offsetMs, latest);
+}
+function actedIds(events) {
+  const lastClock = events.map((e) => e.actor.actorKind).lastIndexOf("system");
+  return new Set(
+    events.slice(lastClock + 1).flatMap((e) => e.actor.actorKind === "persona" ? [e.actor.personaId] : [])
+  );
+}
+async function tick(input) {
+  const { game, store, personas, gameId, nowMs, now, deadline } = input;
+  const log = input.log ?? noop;
+  const acted = [];
+  const skipped = [];
+  const deferred = [];
+  const skip = (seatId, message, context = {}) => {
+    skipped.push(seatId);
+    log(message, { gameId, seatId, ...context });
+  };
+  const fail = (what, e) => {
+    log(`${what}: ${e.message}`, { gameId, code: e.code });
+    return err4(e);
+  };
+  const state = await catchUp(game, store, gameId, nowMs);
+  if (state.isErr()) return fail("catchUp", state.error);
+  if (!state.value) return ok4({ acted, skipped, deferred });
+  const phase = game.phaseOf(state.value);
+  if (phase === "complete") return ok4({ acted, skipped, deferred });
+  const [record, events] = await Promise.all([store.getGame(gameId), store.listEvents(gameId)]);
+  if (record.isErr()) return fail("getGame", record.error);
+  if (events.isErr()) return fail("listEvents", events.error);
+  if (!record.value) return fail("getGame", { code: "store", message: "game vanished" });
+  const pulse = game.pulseOf(state.value);
+  const t = pulseTimes(record.value.startedAtMs, record.value.timescale, pulse);
+  const windowStartMs = phase === "open" ? t.openAtMs : t.lockAtMs;
+  const windowEndMs = phase === "open" ? t.lockAtMs : t.resolveAtMs;
+  const windowMs = windowEndMs - windowStartMs;
+  const actedThisPhase = actedIds(events.value);
+  const actedMeanwhile = async (personaId) => (await store.listEvents(gameId)).map((es) => actedIds(es).has(personaId)).unwrapOr(true);
+  for (const [seatId, persona] of personas) {
+    const seat = record.value.seats.find((s) => s.seatId === seatId);
+    if (seat?.kind !== "persona") {
+      skip(seatId, "not a persona seat", { reason: "not_persona_seat" });
+      continue;
+    }
+    if (seat.personaProfileId !== persona.personaId) {
+      skip(seatId, "persona does not match the seat", { reason: "persona_mismatch" });
+      continue;
+    }
+    if (actedThisPhase.has(persona.personaId)) continue;
+    const seed = `${record.value.seed}:${seatId}:${pulse}:${phase}`;
+    const [offset = 0] = actionOffsets(1, windowMs, persona, createRng(`${seed}:when`));
+    if (nowMs < dueAtMs(windowStartMs, windowMs, offset, persona.tier)) continue;
+    const budgetEndMs = Math.min(deadline?.atMs ?? Number.POSITIVE_INFINITY, windowEndMs);
+    const view = await getView(game, store, { gameId, seatId, nowMs });
+    if (view.isErr()) {
+      skip(seatId, `getView: ${view.error.message}`);
+      continue;
+    }
+    const reserveMs = persona.tier === "llm" ? LLM_RESERVE_MS : 0;
+    if (budgetEndMs - now() < Math.max(reserveMs, 1)) {
+      deferred.push(seatId);
+      log("no budget for the decision; deferring the seat", { gameId, seatId, reserveMs });
+      continue;
+    }
+    if (persona.tier === "llm") {
+      const spent = await store.spendLlmCall(gameId);
+      if (spent.isErr()) {
+        skip(seatId, `spendLlmCall: ${spent.error.code}`, { code: spent.error.code });
+        continue;
+      }
+    }
+    let decided;
+    try {
+      decided = await persona.decide({
+        view: view.value.view,
+        rng: createRng(`${seed}:decide`),
+        fraction: (nowMs - windowStartMs) / windowMs
+      });
+    } catch (e) {
+      skip(seatId, `decide: ${e instanceof Error ? e.message : String(e)}`);
+      continue;
+    }
+    if (decided.events.length === 0) {
+      skip(seatId, "decide returned no events", { reason: "no_events" });
+      continue;
+    }
+    const actor = {
+      actorKind: "persona",
+      personaId: persona.personaId,
+      tier: decided.produced?.tier ?? persona.tier,
+      model: decided.produced?.model ?? persona.model
+    };
+    let landed = 0;
+    for (const event of decided.events) {
+      if (landed === 0 && await actedMeanwhile(persona.personaId)) {
+        skip(seatId, "acted meanwhile", { reason: "acted_meanwhile" });
+        break;
+      }
+      const at = now();
+      if (at >= budgetEndMs) {
+        skip(seatId, at >= windowEndMs ? "window closed" : "deadline passed", {
+          reason: at >= windowEndMs ? "window_closed" : "deadline",
+          landed
+        });
+        break;
+      }
+      const r = await submit(game, store, { gameId, seatId, event, nowMs: at, actor });
+      if (r.isErr()) {
+        skip(seatId, `submit: ${r.error.code}`, { code: r.error.code, message: r.error.message });
+        break;
+      }
+      landed++;
+    }
+    if (landed > 0 && landed === decided.events.length) acted.push(seatId);
+  }
+  return ok4({ acted, skipped, deferred });
+}
+export {
+  AnthropicCompleter,
+  FakeCompleter,
+  LLM_MAX_RETRIES,
+  LLM_MAX_TOKENS,
+  LLM_PREFLIGHT_MS,
+  LLM_RESERVE_MS,
+  LLM_TIMEOUT_MS,
+  LLM_WORST_CASE_MS,
+  MIN_WINDOW_MS,
+  SCHEDULER_CADENCE_MS,
+  actionOffsets,
+  dueAtMs,
+  dueReserveMs,
+  llmPersona,
+  mintPersonaProfile,
+  readLlmEnv,
+  tick
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@aghents/gateway",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.125.0",
+    "neverthrow": "^8.1.1",
+    "zod": "^3.24.1",
+    "@aghents/pulse": "0.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.9"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run"
+  }
+}