@openmarket/rooms-client 0.1.0

package/src/agent/armed-mode.ts

@@ -0,0 +1,368 @@
+import {
+  mentionsHandleExplicit as mentionsAgentExplicit,
+  normalizeHandle,
+} from "../shared/mentions.js";
+import type { RoomLedgerEntry } from "../types.js";
+import { RoomLedgerEntryType } from "../types.js";
+
+export { mentionsAgentExplicit, normalizeHandle };
+
+/**
+ * ARMED MODE rules of engagement (RoE), the guardrails for autonomous in-room
+ * posting under the user's identity. These are the named, easy-to-change
+ * defaults. The whole point of armed mode is that the agent posts on its OWN
+ * initiative as the user, so every gate here is a SAFETY limit, not a nicety:
+ * each one independently blocks an autonomous post, and a post happens only when
+ * ALL of them allow it (see `canPostAutonomously`).
+ *
+ * Defaults DISARMED: with nothing armed there is zero autonomous posting and the
+ * TUI behaves exactly as before. Arming is in-memory per session, never
+ * persisted (a fresh launch is always disarmed).
+ */
+export const ARMED_RULES = {
+  /** Minimum gap between two autonomous posts in the SAME room. */
+  cooldownMs: 30_000,
+  /** Max autonomous posts per room in any rolling 60-minute window. When hit
+   *  the loop PAUSES (skips) until the window frees; it does NOT disarm. */
+  hourlyCap: 10,
+  /** Rolling window the hourly cap is measured over. */
+  hourlyWindowMs: 60 * 60_000,
+  /** Max autonomous posts in a row with no intervening human message. When hit
+   *  the loop PAUSES until a human speaks; it does NOT disarm. */
+  chainLimit: 3,
+  /** Hard per-armed-session TOKEN budget across all armed turns in a room.
+   *  Token spend is read from turn-reported usage when the provider supplies it.
+   *  Exceeding this AUTO-DISARMS the room (this is the cost guard). */
+  tokenBudget: 200_000,
+  /** Fallback hard cap on autonomous posts per armed session, used as the cost
+   *  guard when the provider reports no token usage (most providers don't on
+   *  streaming turns). Exceeding this ALSO auto-disarms. So the cost guard is
+   *  always effective: whichever of tokens / posts trips first disarms. */
+  maxPostsPerSession: 40,
+  /** Settle window before deciding, so a burst of messages is judged once with
+   *  full context (reuses the room-monitor settle idea). */
+  settleMs: 2_500,
+  /** Hard cap on an autonomous post's length. Longer drafts are skipped, not
+   *  truncated (a half-sentence posted as the user is worse than silence). */
+  maxPostChars: 600,
+  /** Consecutive turn/post errors that auto-disarm the room (kill switch). */
+  maxConsecutiveErrors: 3,
+} as const;
+
+/**
+ * Per-verb grants for armed mode. Some verbs are too consequential to ride the
+ * default armed toolset (which is otherwise market/research reads only): they
+ * are OFF unless the operator explicitly grants them for the session. `secrets_send`
+ * lets an armed agent seal-and-post autonomously; default DENY, since an
+ * untrusted @mention must never be able to make the agent exfiltrate a sealed
+ * value. Grants are in-memory per session, never persisted (a fresh launch
+ * grants nothing).
+ */
+export const ARMED_GRANTABLE_VERBS = ["secrets_send"] as const;
+export type ArmedGrantableVerb = (typeof ARMED_GRANTABLE_VERBS)[number];
+
+const armedVerbGrants = new Set<ArmedGrantableVerb>();
+
+export function grantArmedVerb(verb: ArmedGrantableVerb): void {
+  armedVerbGrants.add(verb);
+}
+
+export function revokeArmedVerb(verb: ArmedGrantableVerb): void {
+  armedVerbGrants.delete(verb);
+}
+
+export function isArmedVerbGranted(verb: ArmedGrantableVerb): boolean {
+  return armedVerbGrants.has(verb);
+}
+
+/** The extra verb names an armed turn may advertise given the current grants.
+ *  Appended to `armedSafeToolNames()` at the armed call site. */
+export function grantedArmedVerbNames(): string[] {
+  return ARMED_GRANTABLE_VERBS.filter((verb) => armedVerbGrants.has(verb));
+}
+
+/** Test/lifecycle helper: drop every grant (a fresh session grants nothing). */
+export function clearArmedVerbGrants(): void {
+  armedVerbGrants.clear();
+}
+
+/**
+ * Mutable per-room armed state. Lives only in memory and only while the room is
+ * armed; `disarm` drops it. Caps are tracked here and checked BEFORE every
+ * autonomous post.
+ */
+export interface ArmedRoomState {
+  /** Room id (e.g. "room:btc") this state guards. */
+  readonly roomId: string;
+  /** Timestamps (ms) of autonomous posts this session, used for the cooldown
+   *  and the rolling hourly cap. */
+  postTimes: number[];
+  /** Autonomous posts in a row with no intervening human message. Reset to 0
+   *  whenever a human speaks in the room. */
+  consecutiveAutoPosts: number;
+  /** Total autonomous posts this armed session (cost-guard fallback counter). */
+  postsThisSession: number;
+  /** Total tokens spent by armed turns this session (cost guard, when the
+   *  provider reports usage; otherwise stays 0 and the post counter governs). */
+  tokensThisSession: number;
+  /** Consecutive turn/post errors; resets on any clean turn. At
+   *  `maxConsecutiveErrors` the room auto-disarms. */
+  consecutiveErrors: number;
+  /** The highest room seq this loop has already evaluated, so re-entry doesn't
+   *  re-trigger on already-seen messages. */
+  lastEvaluatedSeq: number;
+}
+
+/** A fresh armed state for a newly armed room. */
+export function makeArmedRoomState(roomId: string, lastSeq = 0): ArmedRoomState {
+  return {
+    roomId,
+    postTimes: [],
+    consecutiveAutoPosts: 0,
+    postsThisSession: 0,
+    tokensThisSession: 0,
+    consecutiveErrors: 0,
+    lastEvaluatedSeq: lastSeq,
+  };
+}
+
+/**
+ * Whether a single incoming entry is a qualifying TRIGGER: a NEW human POST in
+ * the room that @mentions the user's own handle. Agent posts, system entries,
+ * the user's own posts, and non-mentions never trigger. Pure.
+ */
+export function isTriggeringEntry(
+  entry: RoomLedgerEntry,
+  ownHandle: string,
+  ownUserId: string,
+): boolean {
+  if (entry.type !== RoomLedgerEntryType.POST) return false;
+  if (entry.isAgent) return false;
+  if (!entry.text?.trim()) return false;
+  // Never trigger on our own message (we post as this handle/userId).
+  const fromHandle = normalizeHandle(entry.handle).toLowerCase();
+  const me = normalizeHandle(ownHandle).toLowerCase();
+  if (entry.userId === ownUserId) return false;
+  if (me.length > 0 && fromHandle === me) return false;
+  // Must EXPLICITLY @mention the user's own handle. A bare-substring match (the
+  // old mentionsAgent) fired on ordinary words for short handles like "may" /
+  // "btc"; armed posting has no human review, so it triggers ONLY on an `@handle`
+  // token. Empty handle never matches (mentionsAgentExplicit guards it).
+  return mentionsAgentExplicit(entry.text, ownHandle);
+}
+
+/**
+ * The newest qualifying trigger among entries strictly newer than
+ * `afterSeq`, or null if none. Used by the loop to decide whether the latest
+ * batch of room messages contains a reason to act. Pure.
+ */
+export function findTrigger(
+  entries: ReadonlyArray<RoomLedgerEntry>,
+  ownHandle: string,
+  ownUserId: string,
+  afterSeq: number,
+): RoomLedgerEntry | null {
+  let found: RoomLedgerEntry | null = null;
+  for (const entry of entries) {
+    if (entry.seq <= afterSeq) continue;
+    if (isTriggeringEntry(entry, ownHandle, ownUserId)) found = entry;
+  }
+  return found;
+}
+
+/** Autonomous posts inside the rolling hourly window as of `now`. */
+export function postsInWindow(state: ArmedRoomState, now = Date.now()): number {
+  const cutoff = now - ARMED_RULES.hourlyWindowMs;
+  return state.postTimes.filter((t) => t > cutoff).length;
+}
+
+/** Remaining cooldown (ms) before the next autonomous post is allowed; 0 when
+ *  free. */
+export function cooldownRemaining(state: ArmedRoomState, now = Date.now()): number {
+  const last = state.postTimes.at(-1);
+  if (last === undefined) return 0;
+  return Math.max(0, ARMED_RULES.cooldownMs - (now - last));
+}
+
+export type CapBlock = "cooldown" | "hourly" | "chain" | "budget";
+
+/**
+ * Which cap (if any) blocks an autonomous post RIGHT NOW, or null when every
+ * cap allows it. Order matters only for the reported reason; all are hard. Pure
+ * and exported so each gate is unit-testable in isolation.
+ *
+ * - cooldown: < cooldownMs since the last autonomous post.
+ * - hourly:   >= hourlyCap autonomous posts in the rolling window (PAUSE).
+ * - chain:    >= chainLimit autonomous posts with no human between (PAUSE).
+ * - budget:   token spend OR post count over the session cost guard (DISARM).
+ */
+export function capBlocking(state: ArmedRoomState, now = Date.now()): CapBlock | null {
+  if (budgetExceeded(state)) return "budget";
+  if (cooldownRemaining(state, now) > 0) return "cooldown";
+  if (postsInWindow(state, now) >= ARMED_RULES.hourlyCap) return "hourly";
+  if (state.consecutiveAutoPosts >= ARMED_RULES.chainLimit) return "chain";
+  return null;
+}
+
+/**
+ * Whether the session cost guard is spent: token spend over budget OR (the
+ * provider-agnostic fallback) post count over the per-session max. Either
+ * tripping AUTO-DISARMS the room. Pure.
+ */
+export function budgetExceeded(state: ArmedRoomState): boolean {
+  if (state.tokensThisSession >= ARMED_RULES.tokenBudget) return true;
+  if (state.postsThisSession >= ARMED_RULES.maxPostsPerSession) return true;
+  return false;
+}
+
+export type ContentVerdict = { ok: true; text: string } | { ok: false; reason: string };
+
+// Secret/credential shapes that must never be posted as the user. Matches the
+// agent logger's redaction intent: provider API keys, bearer tokens, OM keys,
+// and long hex/base64 secrets. A draft containing any of these is dropped whole.
+const SECRET_PATTERNS: ReadonlyArray<RegExp> = [
+  /sk-[A-Za-z0-9_-]{16,}/, // OpenAI / Anthropic style keys
+  /sk-ant-[A-Za-z0-9_-]{8,}/,
+  /sk-or-[A-Za-z0-9_-]{8,}/,
+  /\bom_[A-Za-z0-9]{16,}\b/, // OpenMarket api keys
+  /\bBearer\s+[A-Za-z0-9._-]{12,}/i,
+  /\bxox[baprs]-[A-Za-z0-9-]{10,}/, // Slack tokens
+  /\bgh[pousr]_[A-Za-z0-9]{20,}/, // GitHub tokens
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+  /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{6,}/, // JWTs
+];
+
+// Any URL/link: armed posting blocks links outright (a posted link as the user
+// is both a spam and an exfiltration vector). Covers explicit schemes, www
+// forms, and bare domains with or without a path.
+const LINK_PATTERN =
+  /\b(?:https?:\/\/|www\.)\S+|\b[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*\.[a-z]{2,24}(?:\/\S*)?\b/i;
+
+/**
+ * CONTENT GUARD applied to a candidate autonomous post BEFORE it is sent.
+ * Rejects: empty/whitespace, anything matching a secret/credential pattern,
+ * anything containing a link/URL, and anything over the length cap. On pass,
+ * returns the trimmed text to post. Pure and exported for unit testing: this
+ * is the last line of defense before text goes out as the user.
+ */
+export function guardAutonomousContent(raw: string): ContentVerdict {
+  const text = raw.trim();
+  if (text.length === 0) return { ok: false, reason: "empty" };
+  if (text.length > ARMED_RULES.maxPostChars) {
+    return { ok: false, reason: `too long (${text.length} > ${ARMED_RULES.maxPostChars})` };
+  }
+  for (const pattern of SECRET_PATTERNS) {
+    if (pattern.test(text)) return { ok: false, reason: "looks like it contains a secret" };
+  }
+  if (LINK_PATTERN.test(text)) return { ok: false, reason: "contains a link" };
+  return { ok: true, text };
+}
+
+export type PostDecision =
+  | { post: true; text: string }
+  | { post: false; reason: string; disarm: boolean };
+
+/**
+ * THE single gate in front of every autonomous post. Returns `{ post: true }`
+ * ONLY when ALL hold:
+ *   1. the room is armed (the caller only invokes this for an armed room, and
+ *      passes its live state),
+ *   2. there is a qualifying trigger (own-handle @mention in a new human msg),
+ *   3. every cap allows it (cooldown AND hourly AND chain AND budget), and
+ *   4. the content guard passes.
+ * Any failure returns `{ post: false }` with a reason; `disarm` is true only
+ * when the failure is the cost-guard (budget), the one cap that auto-disarms
+ * rather than pausing. Pure, so the full && chain is unit-testable end to end
+ * without a TUI or network.
+ */
+export function canPostAutonomously(input: {
+  state: ArmedRoomState;
+  trigger: RoomLedgerEntry | null;
+  candidate: string;
+  now?: number;
+}): PostDecision {
+  const now = input.now ?? Date.now();
+  if (!input.trigger) return { post: false, reason: "no trigger", disarm: false };
+  const cap = capBlocking(input.state, now);
+  if (cap !== null) {
+    return { post: false, reason: `cap:${cap}`, disarm: cap === "budget" };
+  }
+  const verdict = guardAutonomousContent(input.candidate);
+  if (!verdict.ok) return { post: false, reason: `content:${verdict.reason}`, disarm: false };
+  return { post: true, text: verdict.text };
+}
+
+/**
+ * Record a completed autonomous post against the caps: stamp the time (cooldown
+ * + hourly), bump the consecutive-chain and session counters. Call AFTER a
+ * successful `post()`. Mutates `state`.
+ */
+export function recordAutonomousPost(state: ArmedRoomState, now = Date.now()): void {
+  state.postTimes.push(now);
+  // Keep the time list from growing without bound on a long session; only the
+  // rolling window matters for the cap.
+  const cutoff = now - ARMED_RULES.hourlyWindowMs;
+  state.postTimes = state.postTimes.filter((t) => t > cutoff);
+  state.consecutiveAutoPosts += 1;
+  state.postsThisSession += 1;
+}
+
+/** Record token spend from an armed turn against the session cost guard. Reads
+ *  `totalTokens` from a turn's `usage` (pi-ai shape) when present; a no-op when
+ *  the provider reported nothing (the post counter is the fallback guard). */
+export function recordArmedTurnUsage(
+  state: ArmedRoomState,
+  usage: Record<string, unknown> | undefined,
+): void {
+  const total = readTotalTokens(usage);
+  if (total > 0) state.tokensThisSession += total;
+}
+
+function readTotalTokens(usage: Record<string, unknown> | undefined): number {
+  if (!usage) return 0;
+  const direct = usage.totalTokens;
+  if (typeof direct === "number" && Number.isFinite(direct) && direct > 0) return direct;
+  // Fall back to summing input + output if a client reports those instead.
+  const input = typeof usage.input === "number" ? usage.input : 0;
+  const output = typeof usage.output === "number" ? usage.output : 0;
+  const sum = input + output;
+  return Number.isFinite(sum) && sum > 0 ? sum : 0;
+}
+
+/** A human (non-agent) POST that is NOT our own resets the consecutive-chain
+ *  counter, freeing a chain-limit pause. Pure. */
+export function isHumanResetEntry(
+  entry: RoomLedgerEntry,
+  ownHandle: string,
+  ownUserId: string,
+): boolean {
+  if (entry.type !== RoomLedgerEntryType.POST) return false;
+  if (entry.isAgent) return false;
+  if (entry.userId === ownUserId) return false;
+  const fromHandle = normalizeHandle(entry.handle).toLowerCase();
+  const me = normalizeHandle(ownHandle).toLowerCase();
+  if (me.length > 0 && fromHandle === me) return false;
+  return Boolean(entry.text?.trim());
+}
+
+/** Note a turn/post error against the kill switch; returns true once the room
+ *  should auto-disarm (>= maxConsecutiveErrors in a row). Mutates `state`. */
+export function noteArmedError(state: ArmedRoomState): boolean {
+  state.consecutiveErrors += 1;
+  return state.consecutiveErrors >= ARMED_RULES.maxConsecutiveErrors;
+}
+
+/** Reset the consecutive-error counter after a clean armed turn. */
+export function clearArmedErrors(state: ArmedRoomState): void {
+  state.consecutiveErrors = 0;
+}
+
+export function countConsecutiveAgentPosts(entries: RoomLedgerEntry[]): number {
+  let count = 0;
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entry = entries[index];
+    if (!entry || entry.type !== RoomLedgerEntryType.POST || !entry.isAgent) break;
+    count += 1;
+  }
+  return count;
+}

package/src/agent/clients/common.ts

@@ -0,0 +1,91 @@
+import { getProviders, type KnownProvider } from "@earendil-works/pi-ai";
+
+export type SurfaceId = "cli" | "telegram" | "discord" | "slack" | "webui";
+
+export interface AgentToolCall {
+  id: string;
+  name: string;
+  args: unknown;
+}
+
+export type AgentMessage =
+  | { role: "user"; content: string }
+  | { role: "assistant"; content: string; toolCalls?: AgentToolCall[] }
+  | { role: "tool"; content: string; toolCallId: string; name: string };
+
+export interface ToolDispatchResult {
+  isError?: true;
+  content: string;
+}
+
+export interface LlmTool {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  handler: (args: unknown) => Promise<ToolDispatchResult>;
+}
+
+/** OM-level provider for any OpenAI-compatible /v1/chat/completions endpoint
+ *  (Ollama, vLLM, LM Studio, llama.cpp, custom proxies). Not a pi-ai
+ *  KnownProvider: the model object is constructed at turn time from the
+ *  credential's stored base URL instead of pi-ai's catalog. */
+export const OPENAI_COMPATIBLE_PROVIDER = "openai-compatible" as const;
+
+export type LlmProvider = KnownProvider | typeof OPENAI_COMPATIBLE_PROVIDER;
+
+// Provider-resolution precedence (authProviderCandidates): these are tried
+// before any store.order / generic provider. Invariant: an active profile for
+// an earlier provider here shadows a later-configured non-primary one (groq,
+// openai-compatible, …). The headless/env path short-circuits this, but an
+// interactive switch via `om init` to a non-primary provider only takes effect
+// once the shadowing primary profile is removed. Changing that is a product
+// decision (explicit active-provider selection), not a per-provider concern.
+export const PRIMARY_LLM_PROVIDERS: readonly LlmProvider[] = [
+  "anthropic",
+  "openai-codex",
+  "openai",
+  "google",
+  "openrouter",
+];
+
+let knownProviderSet: Set<string> | null = null;
+
+export function isLlmProvider(value: string): value is LlmProvider {
+  if (value === OPENAI_COMPATIBLE_PROVIDER) return true;
+  if (knownProviderSet === null) {
+    knownProviderSet = new Set(getProviders());
+  }
+  return knownProviderSet.has(value);
+}
+
+export type TurnEvent =
+  | { kind: "assistant.text"; delta: string }
+  | { kind: "tool.call"; id: string; name: string; args: unknown }
+  | { kind: "tool.result"; id: string; name: string; result: ToolDispatchResult }
+  | { kind: "turn.done"; usage?: Record<string, unknown> }
+  | { kind: "turn.error"; code?: string; message: string };
+
+export interface RunLlmTurnInput {
+  apiKey: string;
+  system: string;
+  messages: AgentMessage[];
+  tools: LlmTool[];
+  model: string;
+  signal?: AbortSignal | undefined;
+}
+
+export type RunLlmTurn = (input: RunLlmTurnInput) => AsyncIterable<TurnEvent>;
+
+export function stringifyToolContent(value: unknown): string {
+  if (value === undefined) return "";
+  if (typeof value === "string") return value;
+  return JSON.stringify(value, null, 2);
+}
+
+export function parseToolArguments(raw: unknown): unknown {
+  if (raw === undefined || raw === null) return {};
+  if (typeof raw !== "string") return raw;
+  const trimmed = raw.trim();
+  if (!trimmed) return {};
+  return JSON.parse(trimmed) as unknown;
+}

package/src/agent/lane-draft.ts

@@ -0,0 +1,47 @@
+// The private-lane DRAFT contract, shared by every surface that runs a lane
+// co-pilot (the TUI and the /rooms GUI): the lane turn may end with a final
+// `DRAFT: <message>` line, which the surface stages into the PUBLIC composer
+// for the user to send. Pure logic, browser-safe.
+
+/**
+ * The exact prompt line teaching the model to write drafts in the user's own
+ * voice (Persona). Describes the CHARACTER of the voice only (the persona
+ * string is a style description, never example messages), so the model matches
+ * register without parroting canned lines.
+ */
+export function personaVoiceDirective(persona: string): string {
+  return `Write as the user, in their voice. Their style: ${persona.trim()}. Match this voice in any DRAFT you produce.`;
+}
+
+export type LaneTurnOutcome = { kind: "stage-draft"; draft: string } | { kind: "stay-in-lane" };
+
+export function planLaneTurnOutcome(answer: string, aborted: boolean): LaneTurnOutcome {
+  if (aborted) return { kind: "stay-in-lane" };
+  const draft = extractPublicDraft(answer);
+  return draft ? { kind: "stage-draft", draft } : { kind: "stay-in-lane" };
+}
+
+export function extractPublicDraft(answer: string): string | null {
+  const lines = answer.split(/\r?\n/);
+  let lastLine: string | undefined;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i];
+    if (line && line.trim().length > 0) {
+      lastLine = line;
+      break;
+    }
+  }
+  const match = lastLine?.match(/^\s*(?:public\s+)?draft\s*:\s*(.+?)\s*$/i);
+  const draft = match?.[1]?.trim();
+  return draft ? stripWrappingQuotes(draft) : null;
+}
+
+function stripWrappingQuotes(value: string): string {
+  if (value.length < 2) return value;
+  const first = value[0];
+  const last = value[value.length - 1];
+  if ((first === '"' && last === '"') || (first === "'" && last === "'")) {
+    return value.slice(1, -1).trim();
+  }
+  return value;
+}