Include full contents of all nested repositories

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

openclaw/extensions/tlon/README.md

@@ -0,0 +1,5 @@
+# Tlon (OpenClaw plugin)
+
+Tlon/Urbit channel plugin for OpenClaw. Supports DMs, group mentions, and thread replies.
+
+Docs: https://docs.openclaw.ai/channels/tlon

openclaw/extensions/tlon/index.ts

@@ -0,0 +1,17 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+import { tlonPlugin } from "./src/channel.js";
+import { setTlonRuntime } from "./src/runtime.js";
+
+const plugin = {
+  id: "tlon",
+  name: "Tlon",
+  description: "Tlon/Urbit channel plugin",
+  configSchema: emptyPluginConfigSchema(),
+  register(api: OpenClawPluginApi) {
+    setTlonRuntime(api.runtime);
+    api.registerChannel({ plugin: tlonPlugin });
+  },
+};
+
+export default plugin;

openclaw/extensions/tlon/openclaw.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "tlon",
+  "channels": ["tlon"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

openclaw/extensions/tlon/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@openclaw/tlon",
+  "version": "2026.2.26",
+  "description": "OpenClaw Tlon/Urbit channel plugin",
+  "type": "module",
+  "dependencies": {
+    "@urbit/aura": "^3.0.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "channel": {
+      "id": "tlon",
+      "label": "Tlon",
+      "selectionLabel": "Tlon (Urbit)",
+      "docsPath": "/channels/tlon",
+      "docsLabel": "tlon",
+      "blurb": "decentralized messaging on Urbit; install the plugin to enable.",
+      "order": 90,
+      "quickstartAllowFrom": true
+    },
+    "install": {
+      "npmSpec": "@openclaw/tlon",
+      "localPath": "extensions/tlon",
+      "defaultChoice": "npm"
+    }
+  }
+}

openclaw/extensions/tlon/src/account-fields.ts

@@ -0,0 +1,25 @@
+export type TlonAccountFieldsInput = {
+  ship?: string;
+  url?: string;
+  code?: string;
+  allowPrivateNetwork?: boolean;
+  groupChannels?: string[];
+  dmAllowlist?: string[];
+  autoDiscoverChannels?: boolean;
+};
+
+export function buildTlonAccountFields(input: TlonAccountFieldsInput) {
+  return {
+    ...(input.ship ? { ship: input.ship } : {}),
+    ...(input.url ? { url: input.url } : {}),
+    ...(input.code ? { code: input.code } : {}),
+    ...(typeof input.allowPrivateNetwork === "boolean"
+      ? { allowPrivateNetwork: input.allowPrivateNetwork }
+      : {}),
+    ...(input.groupChannels ? { groupChannels: input.groupChannels } : {}),
+    ...(input.dmAllowlist ? { dmAllowlist: input.dmAllowlist } : {}),
+    ...(typeof input.autoDiscoverChannels === "boolean"
+      ? { autoDiscoverChannels: input.autoDiscoverChannels }
+      : {}),
+  };
+}

openclaw/extensions/tlon/src/channel.ts

@@ -0,0 +1,384 @@
+import type {
+  ChannelAccountSnapshot,
+  ChannelOutboundAdapter,
+  ChannelPlugin,
+  ChannelSetupInput,
+  OpenClawConfig,
+} from "openclaw/plugin-sdk";
+import {
+  applyAccountNameToChannelSection,
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+} from "openclaw/plugin-sdk";
+import { buildTlonAccountFields } from "./account-fields.js";
+import { tlonChannelConfigSchema } from "./config-schema.js";
+import { monitorTlonProvider } from "./monitor/index.js";
+import { tlonOnboardingAdapter } from "./onboarding.js";
+import { formatTargetHint, normalizeShip, parseTlonTarget } from "./targets.js";
+import { resolveTlonAccount, listTlonAccountIds } from "./types.js";
+import { authenticate } from "./urbit/auth.js";
+import { UrbitChannelClient } from "./urbit/channel-client.js";
+import { ssrfPolicyFromAllowPrivateNetwork } from "./urbit/context.js";
+import { buildMediaText, sendDm, sendGroupMessage } from "./urbit/send.js";
+
+const TLON_CHANNEL_ID = "tlon" as const;
+
+type TlonSetupInput = ChannelSetupInput & {
+  ship?: string;
+  url?: string;
+  code?: string;
+  allowPrivateNetwork?: boolean;
+  groupChannels?: string[];
+  dmAllowlist?: string[];
+  autoDiscoverChannels?: boolean;
+};
+
+function applyTlonSetupConfig(params: {
+  cfg: OpenClawConfig;
+  accountId: string;
+  input: TlonSetupInput;
+}): OpenClawConfig {
+  const { cfg, accountId, input } = params;
+  const useDefault = accountId === DEFAULT_ACCOUNT_ID;
+  const namedConfig = applyAccountNameToChannelSection({
+    cfg,
+    channelKey: "tlon",
+    accountId,
+    name: input.name,
+  });
+  const base = namedConfig.channels?.tlon ?? {};
+
+  const payload = buildTlonAccountFields(input);
+
+  if (useDefault) {
+    return {
+      ...namedConfig,
+      channels: {
+        ...namedConfig.channels,
+        tlon: {
+          ...base,
+          enabled: true,
+          ...payload,
+        },
+      },
+    };
+  }
+
+  return {
+    ...namedConfig,
+    channels: {
+      ...namedConfig.channels,
+      tlon: {
+        ...base,
+        enabled: base.enabled ?? true,
+        accounts: {
+          ...(base as { accounts?: Record<string, unknown> }).accounts,
+          [accountId]: {
+            ...(base as { accounts?: Record<string, Record<string, unknown>> }).accounts?.[
+              accountId
+            ],
+            enabled: true,
+            ...payload,
+          },
+        },
+      },
+    },
+  };
+}
+
+const tlonOutbound: ChannelOutboundAdapter = {
+  deliveryMode: "direct",
+  textChunkLimit: 10000,
+  resolveTarget: ({ to }) => {
+    const parsed = parseTlonTarget(to ?? "");
+    if (!parsed) {
+      return {
+        ok: false,
+        error: new Error(`Invalid Tlon target. Use ${formatTargetHint()}`),
+      };
+    }
+    if (parsed.kind === "direct") {
+      return { ok: true, to: parsed.ship };
+    }
+    return { ok: true, to: parsed.nest };
+  },
+  sendText: async ({ cfg, to, text, accountId, replyToId, threadId }) => {
+    const account = resolveTlonAccount(cfg, accountId ?? undefined);
+    if (!account.configured || !account.ship || !account.url || !account.code) {
+      throw new Error("Tlon account not configured");
+    }
+
+    const parsed = parseTlonTarget(to);
+    if (!parsed) {
+      throw new Error(`Invalid Tlon target. Use ${formatTargetHint()}`);
+    }
+
+    const ssrfPolicy = ssrfPolicyFromAllowPrivateNetwork(account.allowPrivateNetwork);
+    const cookie = await authenticate(account.url, account.code, { ssrfPolicy });
+    const api = new UrbitChannelClient(account.url, cookie, {
+      ship: account.ship.replace(/^~/, ""),
+      ssrfPolicy,
+    });
+
+    try {
+      const fromShip = normalizeShip(account.ship);
+      if (parsed.kind === "direct") {
+        return await sendDm({
+          api,
+          fromShip,
+          toShip: parsed.ship,
+          text,
+        });
+      }
+      const replyId = (replyToId ?? threadId) ? String(replyToId ?? threadId) : undefined;
+      return await sendGroupMessage({
+        api,
+        fromShip,
+        hostShip: parsed.hostShip,
+        channelName: parsed.channelName,
+        text,
+        replyToId: replyId,
+      });
+    } finally {
+      await api.close();
+    }
+  },
+  sendMedia: async ({ cfg, to, text, mediaUrl, accountId, replyToId, threadId }) => {
+    const mergedText = buildMediaText(text, mediaUrl);
+    return await tlonOutbound.sendText!({
+      cfg,
+      to,
+      text: mergedText,
+      accountId,
+      replyToId,
+      threadId,
+    });
+  },
+};
+
+export const tlonPlugin: ChannelPlugin = {
+  id: TLON_CHANNEL_ID,
+  meta: {
+    id: TLON_CHANNEL_ID,
+    label: "Tlon",
+    selectionLabel: "Tlon (Urbit)",
+    docsPath: "/channels/tlon",
+    docsLabel: "tlon",
+    blurb: "Decentralized messaging on Urbit",
+    aliases: ["urbit"],
+    order: 90,
+  },
+  capabilities: {
+    chatTypes: ["direct", "group", "thread"],
+    media: false,
+    reply: true,
+    threads: true,
+  },
+  onboarding: tlonOnboardingAdapter,
+  reload: { configPrefixes: ["channels.tlon"] },
+  configSchema: tlonChannelConfigSchema,
+  config: {
+    listAccountIds: (cfg) => listTlonAccountIds(cfg),
+    resolveAccount: (cfg, accountId) => resolveTlonAccount(cfg, accountId ?? undefined),
+    defaultAccountId: () => "default",
+    setAccountEnabled: ({ cfg, accountId, enabled }) => {
+      const useDefault = !accountId || accountId === "default";
+      if (useDefault) {
+        return {
+          ...cfg,
+          channels: {
+            ...cfg.channels,
+            tlon: {
+              ...(cfg.channels?.tlon as Record<string, unknown>),
+              enabled,
+            },
+          },
+        } as OpenClawConfig;
+      }
+      return {
+        ...cfg,
+        channels: {
+          ...cfg.channels,
+          tlon: {
+            ...(cfg.channels?.tlon as Record<string, unknown>),
+            accounts: {
+              ...cfg.channels?.tlon?.accounts,
+              [accountId]: {
+                ...cfg.channels?.tlon?.accounts?.[accountId],
+                enabled,
+              },
+            },
+          },
+        },
+      } as OpenClawConfig;
+    },
+    deleteAccount: ({ cfg, accountId }) => {
+      const useDefault = !accountId || accountId === "default";
+      if (useDefault) {
+        // oxlint-disable-next-line no-unused-vars
+        const { ship, code, url, name, ...rest } = (cfg.channels?.tlon ?? {}) as Record<
+          string,
+          unknown
+        >;
+        return {
+          ...cfg,
+          channels: {
+            ...cfg.channels,
+            tlon: rest,
+          },
+        } as OpenClawConfig;
+      }
+      // oxlint-disable-next-line no-unused-vars
+      const { [accountId]: removed, ...remainingAccounts } = (cfg.channels?.tlon?.accounts ??
+        {}) as Record<string, unknown>;
+      return {
+        ...cfg,
+        channels: {
+          ...cfg.channels,
+          tlon: {
+            ...(cfg.channels?.tlon as Record<string, unknown>),
+            accounts: remainingAccounts,
+          },
+        },
+      } as OpenClawConfig;
+    },
+    isConfigured: (account) => account.configured,
+    describeAccount: (account) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      ship: account.ship,
+      url: account.url,
+    }),
+  },
+  setup: {
+    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
+    applyAccountName: ({ cfg, accountId, name }) =>
+      applyAccountNameToChannelSection({
+        cfg: cfg,
+        channelKey: "tlon",
+        accountId,
+        name,
+      }),
+    validateInput: ({ cfg, accountId, input }) => {
+      const setupInput = input as TlonSetupInput;
+      const resolved = resolveTlonAccount(cfg, accountId ?? undefined);
+      const ship = setupInput.ship?.trim() || resolved.ship;
+      const url = setupInput.url?.trim() || resolved.url;
+      const code = setupInput.code?.trim() || resolved.code;
+      if (!ship) {
+        return "Tlon requires --ship.";
+      }
+      if (!url) {
+        return "Tlon requires --url.";
+      }
+      if (!code) {
+        return "Tlon requires --code.";
+      }
+      return null;
+    },
+    applyAccountConfig: ({ cfg, accountId, input }) =>
+      applyTlonSetupConfig({
+        cfg: cfg,
+        accountId,
+        input: input as TlonSetupInput,
+      }),
+  },
+  messaging: {
+    normalizeTarget: (target) => {
+      const parsed = parseTlonTarget(target);
+      if (!parsed) {
+        return target.trim();
+      }
+      if (parsed.kind === "direct") {
+        return parsed.ship;
+      }
+      return parsed.nest;
+    },
+    targetResolver: {
+      looksLikeId: (target) => Boolean(parseTlonTarget(target)),
+      hint: formatTargetHint(),
+    },
+  },
+  outbound: tlonOutbound,
+  status: {
+    defaultRuntime: {
+      accountId: "default",
+      running: false,
+      lastStartAt: null,
+      lastStopAt: null,
+      lastError: null,
+    },
+    collectStatusIssues: (accounts) => {
+      return accounts.flatMap((account) => {
+        if (!account.configured) {
+          return [
+            {
+              channel: TLON_CHANNEL_ID,
+              accountId: account.accountId,
+              kind: "config",
+              message: "Account not configured (missing ship, code, or url)",
+            },
+          ];
+        }
+        return [];
+      });
+    },
+    buildChannelSummary: ({ snapshot }) => ({
+      configured: snapshot.configured ?? false,
+      ship: (snapshot as { ship?: string | null }).ship ?? null,
+      url: (snapshot as { url?: string | null }).url ?? null,
+    }),
+    probeAccount: async ({ account }) => {
+      if (!account.configured || !account.ship || !account.url || !account.code) {
+        return { ok: false, error: "Not configured" };
+      }
+      try {
+        const ssrfPolicy = ssrfPolicyFromAllowPrivateNetwork(account.allowPrivateNetwork);
+        const cookie = await authenticate(account.url, account.code, { ssrfPolicy });
+        const api = new UrbitChannelClient(account.url, cookie, {
+          ship: account.ship.replace(/^~/, ""),
+          ssrfPolicy,
+        });
+        try {
+          await api.getOurName();
+          return { ok: true };
+        } finally {
+          await api.close();
+        }
+      } catch (error) {
+        return { ok: false, error: (error as { message?: string })?.message ?? String(error) };
+      }
+    },
+    buildAccountSnapshot: ({ account, runtime, probe }) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      ship: account.ship,
+      url: account.url,
+      running: runtime?.running ?? false,
+      lastStartAt: runtime?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? null,
+      lastError: runtime?.lastError ?? null,
+      probe,
+    }),
+  },
+  gateway: {
+    startAccount: async (ctx) => {
+      const account = ctx.account;
+      ctx.setStatus({
+        accountId: account.accountId,
+        ship: account.ship,
+        url: account.url,
+      } as ChannelAccountSnapshot);
+      ctx.log?.info(`[${account.accountId}] starting Tlon provider for ${account.ship ?? "tlon"}`);
+      return monitorTlonProvider({
+        runtime: ctx.runtime,
+        abortSignal: ctx.abortSignal,
+        accountId: account.accountId,
+      });
+    },
+  },
+};

openclaw/extensions/tlon/src/config-schema.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import { TlonAuthorizationSchema, TlonConfigSchema } from "./config-schema.js";
+
+describe("Tlon config schema", () => {
+  it("accepts channelRules with string keys", () => {
+    const parsed = TlonAuthorizationSchema.parse({
+      channelRules: {
+        "chat/~zod/test": {
+          mode: "open",
+          allowedShips: ["~zod"],
+        },
+      },
+    });
+
+    expect(parsed.channelRules?.["chat/~zod/test"]?.mode).toBe("open");
+  });
+
+  it("accepts accounts with string keys", () => {
+    const parsed = TlonConfigSchema.parse({
+      accounts: {
+        primary: {
+          ship: "~zod",
+          url: "https://example.com",
+          code: "code-123",
+        },
+      },
+    });
+
+    expect(parsed.accounts?.primary?.ship).toBe("~zod");
+  });
+});

openclaw/extensions/tlon/src/config-schema.ts

@@ -0,0 +1,41 @@
+import { buildChannelConfigSchema } from "openclaw/plugin-sdk";
+import { z } from "zod";
+
+const ShipSchema = z.string().min(1);
+const ChannelNestSchema = z.string().min(1);
+
+export const TlonChannelRuleSchema = z.object({
+  mode: z.enum(["restricted", "open"]).optional(),
+  allowedShips: z.array(ShipSchema).optional(),
+});
+
+export const TlonAuthorizationSchema = z.object({
+  channelRules: z.record(z.string(), TlonChannelRuleSchema).optional(),
+});
+
+const tlonCommonConfigFields = {
+  name: z.string().optional(),
+  enabled: z.boolean().optional(),
+  ship: ShipSchema.optional(),
+  url: z.string().optional(),
+  code: z.string().optional(),
+  allowPrivateNetwork: z.boolean().optional(),
+  groupChannels: z.array(ChannelNestSchema).optional(),
+  dmAllowlist: z.array(ShipSchema).optional(),
+  autoDiscoverChannels: z.boolean().optional(),
+  showModelSignature: z.boolean().optional(),
+  responsePrefix: z.string().optional(),
+} satisfies z.ZodRawShape;
+
+export const TlonAccountSchema = z.object({
+  ...tlonCommonConfigFields,
+});
+
+export const TlonConfigSchema = z.object({
+  ...tlonCommonConfigFields,
+  authorization: TlonAuthorizationSchema.optional(),
+  defaultAuthorizedShips: z.array(ShipSchema).optional(),
+  accounts: z.record(z.string(), TlonAccountSchema).optional(),
+});
+
+export const tlonChannelConfigSchema = buildChannelConfigSchema(TlonConfigSchema);

openclaw/extensions/tlon/src/monitor/discovery.ts

@@ -0,0 +1,78 @@
+import type { RuntimeEnv } from "openclaw/plugin-sdk";
+import { formatChangesDate } from "./utils.js";
+
+export async function fetchGroupChanges(
+  api: { scry: (path: string) => Promise<unknown> },
+  runtime: RuntimeEnv,
+  daysAgo = 5,
+) {
+  try {
+    const changeDate = formatChangesDate(daysAgo);
+    runtime.log?.(`[tlon] Fetching group changes since ${daysAgo} days ago (${changeDate})...`);
+    const changes = await api.scry(`/groups-ui/v5/changes/${changeDate}.json`);
+    if (changes) {
+      runtime.log?.("[tlon] Successfully fetched changes data");
+      return changes;
+    }
+    return null;
+  } catch (error) {
+    runtime.log?.(
+      `[tlon] Failed to fetch changes (falling back to full init): ${(error as { message?: string })?.message ?? String(error)}`,
+    );
+    return null;
+  }
+}
+
+export async function fetchAllChannels(
+  api: { scry: (path: string) => Promise<unknown> },
+  runtime: RuntimeEnv,
+): Promise<string[]> {
+  try {
+    runtime.log?.("[tlon] Attempting auto-discovery of group channels...");
+    const changes = await fetchGroupChanges(api, runtime, 5);
+
+    // oxlint-disable-next-line typescript/no-explicit-any
+    let initData: any;
+    if (changes) {
+      runtime.log?.("[tlon] Changes data received, using full init for channel extraction");
+      initData = await api.scry("/groups-ui/v6/init.json");
+    } else {
+      initData = await api.scry("/groups-ui/v6/init.json");
+    }
+
+    const channels: string[] = [];
+    if (initData && initData.groups) {
+      // oxlint-disable-next-line typescript/no-explicit-any
+      for (const groupData of Object.values(initData.groups as Record<string, any>)) {
+        if (groupData && typeof groupData === "object" && groupData.channels) {
+          for (const channelNest of Object.keys(groupData.channels)) {
+            if (channelNest.startsWith("chat/")) {
+              channels.push(channelNest);
+            }
+          }
+        }
+      }
+    }
+
+    if (channels.length > 0) {
+      runtime.log?.(`[tlon] Auto-discovered ${channels.length} chat channel(s)`);
+      runtime.log?.(
+        `[tlon] Channels: ${channels.slice(0, 5).join(", ")}${channels.length > 5 ? "..." : ""}`,
+      );
+    } else {
+      runtime.log?.("[tlon] No chat channels found via auto-discovery");
+      runtime.log?.("[tlon] Add channels manually to config: channels.tlon.groupChannels");
+    }
+
+    return channels;
+  } catch (error) {
+    runtime.log?.(
+      `[tlon] Auto-discovery failed: ${(error as { message?: string })?.message ?? String(error)}`,
+    );
+    runtime.log?.(
+      "[tlon] To monitor group channels, add them to config: channels.tlon.groupChannels",
+    );
+    runtime.log?.('[tlon] Example: ["chat/~host-ship/channel-name"]');
+    return [];
+  }
+}

openclaw/extensions/tlon/src/monitor/history.ts

@@ -0,0 +1,92 @@
+import type { RuntimeEnv } from "openclaw/plugin-sdk";
+import { extractMessageText } from "./utils.js";
+
+export type TlonHistoryEntry = {
+  author: string;
+  content: string;
+  timestamp: number;
+  id?: string;
+};
+
+const messageCache = new Map<string, TlonHistoryEntry[]>();
+const MAX_CACHED_MESSAGES = 100;
+
+export function cacheMessage(channelNest: string, message: TlonHistoryEntry) {
+  if (!messageCache.has(channelNest)) {
+    messageCache.set(channelNest, []);
+  }
+  const cache = messageCache.get(channelNest);
+  if (!cache) {
+    return;
+  }
+  cache.unshift(message);
+  if (cache.length > MAX_CACHED_MESSAGES) {
+    cache.pop();
+  }
+}
+
+export async function fetchChannelHistory(
+  api: { scry: (path: string) => Promise<unknown> },
+  channelNest: string,
+  count = 50,
+  runtime?: RuntimeEnv,
+): Promise<TlonHistoryEntry[]> {
+  try {
+    const scryPath = `/channels/v4/${channelNest}/posts/newest/${count}/outline.json`;
+    runtime?.log?.(`[tlon] Fetching history: ${scryPath}`);
+
+    // oxlint-disable-next-line typescript/no-explicit-any
+    const data: any = await api.scry(scryPath);
+    if (!data) {
+      return [];
+    }
+
+    // oxlint-disable-next-line typescript/no-explicit-any
+    let posts: any[] = [];
+    if (Array.isArray(data)) {
+      posts = data;
+    } else if (data.posts && typeof data.posts === "object") {
+      posts = Object.values(data.posts);
+    } else if (typeof data === "object") {
+      posts = Object.values(data);
+    }
+
+    const messages = posts
+      .map((item) => {
+        const essay = item.essay || item["r-post"]?.set?.essay;
+        const seal = item.seal || item["r-post"]?.set?.seal;
+
+        return {
+          author: essay?.author || "unknown",
+          content: extractMessageText(essay?.content || []),
+          timestamp: essay?.sent || Date.now(),
+          id: seal?.id,
+        } as TlonHistoryEntry;
+      })
+      .filter((msg) => msg.content);
+
+    runtime?.log?.(`[tlon] Extracted ${messages.length} messages from history`);
+    return messages;
+  } catch (error) {
+    runtime?.log?.(
+      `[tlon] Error fetching channel history: ${(error as { message?: string })?.message ?? String(error)}`,
+    );
+    return [];
+  }
+}
+
+export async function getChannelHistory(
+  api: { scry: (path: string) => Promise<unknown> },
+  channelNest: string,
+  count = 50,
+  runtime?: RuntimeEnv,
+): Promise<TlonHistoryEntry[]> {
+  const cache = messageCache.get(channelNest) ?? [];
+  if (cache.length >= count) {
+    runtime?.log?.(`[tlon] Using cached messages (${cache.length} available)`);
+    return cache.slice(0, count);
+  }
+
+  runtime?.log?.(`[tlon] Cache has ${cache.length} messages, need ${count}, fetching from scry...`);
+  return await fetchChannelHistory(api, channelNest, count, runtime);
+}

openclaw/extensions/tlon/src/monitor/index.ts

@@ -0,0 +1,596 @@
+import type { RuntimeEnv, ReplyPayload, OpenClawConfig } from "openclaw/plugin-sdk";
+import { createLoggerBackedRuntime, createReplyPrefixOptions } from "openclaw/plugin-sdk";
+import { getTlonRuntime } from "../runtime.js";
+import { normalizeShip, parseChannelNest } from "../targets.js";
+import { resolveTlonAccount } from "../types.js";
+import { authenticate } from "../urbit/auth.js";
+import { ssrfPolicyFromAllowPrivateNetwork } from "../urbit/context.js";
+import { sendDm, sendGroupMessage } from "../urbit/send.js";
+import { UrbitSSEClient } from "../urbit/sse-client.js";
+import { fetchAllChannels } from "./discovery.js";
+import { cacheMessage, getChannelHistory } from "./history.js";
+import { createProcessedMessageTracker } from "./processed-messages.js";
+import {
+  extractMessageText,
+  formatModelName,
+  isBotMentioned,
+  isDmAllowed,
+  isSummarizationRequest,
+} from "./utils.js";
+
+function formatError(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+
+export type MonitorTlonOpts = {
+  runtime?: RuntimeEnv;
+  abortSignal?: AbortSignal;
+  accountId?: string | null;
+};
+
+type ChannelAuthorization = {
+  mode?: "restricted" | "open";
+  allowedShips?: string[];
+};
+
+type UrbitMemo = {
+  author?: string;
+  content?: unknown;
+  sent?: number;
+};
+
+type UrbitSeal = {
+  "parent-id"?: string;
+  parent?: string;
+};
+
+type UrbitUpdate = {
+  id?: string | number;
+  response?: {
+    add?: { memo?: UrbitMemo };
+    post?: {
+      id?: string | number;
+      "r-post"?: {
+        set?: { essay?: UrbitMemo; seal?: UrbitSeal };
+        reply?: {
+          id?: string | number;
+          "r-reply"?: { set?: { memo?: UrbitMemo; seal?: UrbitSeal } };
+        };
+      };
+    };
+  };
+};
+
+function resolveChannelAuthorization(
+  cfg: OpenClawConfig,
+  channelNest: string,
+): { mode: "restricted" | "open"; allowedShips: string[] } {
+  const tlonConfig = cfg.channels?.tlon as
+    | {
+        authorization?: { channelRules?: Record<string, ChannelAuthorization> };
+        defaultAuthorizedShips?: string[];
+      }
+    | undefined;
+  const rules = tlonConfig?.authorization?.channelRules ?? {};
+  const rule = rules[channelNest];
+  const allowedShips = rule?.allowedShips ?? tlonConfig?.defaultAuthorizedShips ?? [];
+  const mode = rule?.mode ?? "restricted";
+  return { mode, allowedShips };
+}
+
+export async function monitorTlonProvider(opts: MonitorTlonOpts = {}): Promise<void> {
+  const core = getTlonRuntime();
+  const cfg = core.config.loadConfig();
+  if (cfg.channels?.tlon?.enabled === false) {
+    return;
+  }
+
+  const logger = core.logging.getChildLogger({ module: "tlon-auto-reply" });
+  const runtime: RuntimeEnv =
+    opts.runtime ??
+    createLoggerBackedRuntime({
+      logger,
+    });
+
+  const account = resolveTlonAccount(cfg, opts.accountId ?? undefined);
+  if (!account.enabled) {
+    return;
+  }
+  if (!account.configured || !account.ship || !account.url || !account.code) {
+    throw new Error("Tlon account not configured (ship/url/code required)");
+  }
+
+  const botShipName = normalizeShip(account.ship);
+  runtime.log?.(`[tlon] Starting monitor for ${botShipName}`);
+
+  let api: UrbitSSEClient | null = null;
+  try {
+    const ssrfPolicy = ssrfPolicyFromAllowPrivateNetwork(account.allowPrivateNetwork);
+    runtime.log?.(`[tlon] Attempting authentication to ${account.url}...`);
+    const cookie = await authenticate(account.url, account.code, { ssrfPolicy });
+    api = new UrbitSSEClient(account.url, cookie, {
+      ship: botShipName,
+      ssrfPolicy,
+      logger: {
+        log: (message) => runtime.log?.(message),
+        error: (message) => runtime.error?.(message),
+      },
+    });
+  } catch (error) {
+    runtime.error?.(`[tlon] Failed to authenticate: ${formatError(error)}`);
+    throw error;
+  }
+
+  const processedTracker = createProcessedMessageTracker(2000);
+  let groupChannels: string[] = [];
+
+  if (account.autoDiscoverChannels !== false) {
+    try {
+      const discoveredChannels = await fetchAllChannels(api, runtime);
+      if (discoveredChannels.length > 0) {
+        groupChannels = discoveredChannels;
+      }
+    } catch (error) {
+      runtime.error?.(`[tlon] Auto-discovery failed: ${formatError(error)}`);
+    }
+  }
+
+  if (groupChannels.length === 0 && account.groupChannels.length > 0) {
+    groupChannels = account.groupChannels;
+    runtime.log?.(`[tlon] Using manual groupChannels config: ${groupChannels.join(", ")}`);
+  }
+
+  if (groupChannels.length > 0) {
+    runtime.log?.(
+      `[tlon] Monitoring ${groupChannels.length} group channel(s): ${groupChannels.join(", ")}`,
+    );
+  } else {
+    runtime.log?.("[tlon] No group channels to monitor (DMs only)");
+  }
+
+  const handleIncomingDM = async (update: UrbitUpdate) => {
+    try {
+      const memo = update?.response?.add?.memo;
+      if (!memo) {
+        return;
+      }
+
+      const messageId = update.id != null ? String(update.id) : undefined;
+      if (!processedTracker.mark(messageId)) {
+        return;
+      }
+
+      const senderShip = normalizeShip(memo.author ?? "");
+      if (!senderShip || senderShip === botShipName) {
+        return;
+      }
+
+      const messageText = extractMessageText(memo.content);
+      if (!messageText) {
+        return;
+      }
+
+      if (!isDmAllowed(senderShip, account.dmAllowlist)) {
+        runtime.log?.(`[tlon] Blocked DM from ${senderShip}: not in allowlist`);
+        return;
+      }
+
+      await processMessage({
+        messageId: messageId ?? "",
+        senderShip,
+        messageText,
+        isGroup: false,
+        timestamp: memo.sent || Date.now(),
+      });
+    } catch (error) {
+      runtime.error?.(`[tlon] Error handling DM: ${formatError(error)}`);
+    }
+  };
+
+  const handleIncomingGroupMessage = (channelNest: string) => async (update: UrbitUpdate) => {
+    try {
+      const parsed = parseChannelNest(channelNest);
+      if (!parsed) {
+        return;
+      }
+
+      const post = update?.response?.post?.["r-post"];
+      const essay = post?.set?.essay;
+      const memo = post?.reply?.["r-reply"]?.set?.memo;
+      if (!essay && !memo) {
+        return;
+      }
+
+      const content = memo || essay;
+      if (!content) {
+        return;
+      }
+      const isThreadReply = Boolean(memo);
+      const rawMessageId = isThreadReply ? post?.reply?.id : update?.response?.post?.id;
+      const messageId = rawMessageId != null ? String(rawMessageId) : undefined;
+
+      if (!processedTracker.mark(messageId)) {
+        return;
+      }
+
+      const senderShip = normalizeShip(content.author ?? "");
+      if (!senderShip || senderShip === botShipName) {
+        return;
+      }
+
+      const messageText = extractMessageText(content.content);
+      if (!messageText) {
+        return;
+      }
+
+      cacheMessage(channelNest, {
+        author: senderShip,
+        content: messageText,
+        timestamp: content.sent || Date.now(),
+        id: messageId,
+      });
+
+      const mentioned = isBotMentioned(messageText, botShipName);
+      if (!mentioned) {
+        return;
+      }
+
+      const { mode, allowedShips } = resolveChannelAuthorization(cfg, channelNest);
+      if (mode === "restricted") {
+        if (allowedShips.length === 0) {
+          runtime.log?.(`[tlon] Access denied: ${senderShip} in ${channelNest} (no allowlist)`);
+          return;
+        }
+        const normalizedAllowed = allowedShips.map(normalizeShip);
+        if (!normalizedAllowed.includes(senderShip)) {
+          runtime.log?.(
+            `[tlon] Access denied: ${senderShip} in ${channelNest} (allowed: ${allowedShips.join(", ")})`,
+          );
+          return;
+        }
+      }
+
+      const seal = isThreadReply
+        ? update?.response?.post?.["r-post"]?.reply?.["r-reply"]?.set?.seal
+        : update?.response?.post?.["r-post"]?.set?.seal;
+
+      const parentId = seal?.["parent-id"] || seal?.parent || null;
+
+      await processMessage({
+        messageId: messageId ?? "",
+        senderShip,
+        messageText,
+        isGroup: true,
+        groupChannel: channelNest,
+        groupName: `${parsed.hostShip}/${parsed.channelName}`,
+        timestamp: content.sent || Date.now(),
+        parentId,
+      });
+    } catch (error) {
+      runtime.error?.(`[tlon] Error handling group message: ${formatError(error)}`);
+    }
+  };
+
+  const processMessage = async (params: {
+    messageId: string;
+    senderShip: string;
+    messageText: string;
+    isGroup: boolean;
+    groupChannel?: string;
+    groupName?: string;
+    timestamp: number;
+    parentId?: string | null;
+  }) => {
+    const { messageId, senderShip, isGroup, groupChannel, groupName, timestamp, parentId } = params;
+    let messageText = params.messageText;
+
+    if (isGroup && groupChannel && isSummarizationRequest(messageText)) {
+      try {
+        const history = await getChannelHistory(api, groupChannel, 50, runtime);
+        if (history.length === 0) {
+          const noHistoryMsg =
+            "I couldn't fetch any messages for this channel. It might be empty or there might be a permissions issue.";
+          if (isGroup) {
+            const parsed = parseChannelNest(groupChannel);
+            if (parsed) {
+              await sendGroupMessage({
+                api: api,
+                fromShip: botShipName,
+                hostShip: parsed.hostShip,
+                channelName: parsed.channelName,
+                text: noHistoryMsg,
+              });
+            }
+          } else {
+            await sendDm({
+              api: api,
+              fromShip: botShipName,
+              toShip: senderShip,
+              text: noHistoryMsg,
+            });
+          }
+          return;
+        }
+
+        const historyText = history
+          .map(
+            (msg) => `[${new Date(msg.timestamp).toLocaleString()}] ${msg.author}: ${msg.content}`,
+          )
+          .join("\n");
+
+        messageText =
+          `Please summarize this channel conversation (${history.length} recent messages):\n\n${historyText}\n\n` +
+          "Provide a concise summary highlighting:\n" +
+          "1. Main topics discussed\n" +
+          "2. Key decisions or conclusions\n" +
+          "3. Action items if any\n" +
+          "4. Notable participants";
+      } catch (error) {
+        const errorMsg = `Sorry, I encountered an error while fetching the channel history: ${formatError(error)}`;
+        if (isGroup && groupChannel) {
+          const parsed = parseChannelNest(groupChannel);
+          if (parsed) {
+            await sendGroupMessage({
+              api: api,
+              fromShip: botShipName,
+              hostShip: parsed.hostShip,
+              channelName: parsed.channelName,
+              text: errorMsg,
+            });
+          }
+        } else {
+          await sendDm({ api: api, fromShip: botShipName, toShip: senderShip, text: errorMsg });
+        }
+        return;
+      }
+    }
+
+    const route = core.channel.routing.resolveAgentRoute({
+      cfg,
+      channel: "tlon",
+      accountId: opts.accountId ?? undefined,
+      peer: {
+        kind: isGroup ? "group" : "direct",
+        id: isGroup ? (groupChannel ?? senderShip) : senderShip,
+      },
+    });
+
+    const fromLabel = isGroup ? `${senderShip} in ${groupName}` : senderShip;
+    const body = core.channel.reply.formatAgentEnvelope({
+      channel: "Tlon",
+      from: fromLabel,
+      timestamp,
+      body: messageText,
+    });
+
+    const ctxPayload = core.channel.reply.finalizeInboundContext({
+      Body: body,
+      BodyForAgent: messageText,
+      RawBody: messageText,
+      CommandBody: messageText,
+      From: isGroup ? `tlon:group:${groupChannel}` : `tlon:${senderShip}`,
+      To: `tlon:${botShipName}`,
+      SessionKey: route.sessionKey,
+      AccountId: route.accountId,
+      ChatType: isGroup ? "group" : "direct",
+      ConversationLabel: fromLabel,
+      SenderName: senderShip,
+      SenderId: senderShip,
+      Provider: "tlon",
+      Surface: "tlon",
+      MessageSid: messageId,
+      OriginatingChannel: "tlon",
+      OriginatingTo: `tlon:${isGroup ? groupChannel : botShipName}`,
+    });
+
+    const dispatchStartTime = Date.now();
+
+    const { onModelSelected, ...prefixOptions } = createReplyPrefixOptions({
+      cfg,
+      agentId: route.agentId,
+      channel: "tlon",
+      accountId: route.accountId,
+    });
+    const humanDelay = core.channel.reply.resolveHumanDelayConfig(cfg, route.agentId);
+
+    await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+      ctx: ctxPayload,
+      cfg,
+      dispatcherOptions: {
+        ...prefixOptions,
+        humanDelay,
+        deliver: async (payload: ReplyPayload) => {
+          let replyText = payload.text;
+          if (!replyText) {
+            return;
+          }
+
+          const showSignature =
+            account.showModelSignature ?? cfg.channels?.tlon?.showModelSignature ?? false;
+          if (showSignature) {
+            const extPayload = payload as ReplyPayload & {
+              metadata?: { model?: string };
+              model?: string;
+            };
+            const extRoute = route as typeof route & { model?: string };
+            const defaultModel = cfg.agents?.defaults?.model;
+            const modelInfo =
+              extPayload.metadata?.model ||
+              extPayload.model ||
+              extRoute.model ||
+              (typeof defaultModel === "string" ? defaultModel : defaultModel?.primary);
+            replyText = `${replyText}\n\n_[Generated by ${formatModelName(modelInfo)}]_`;
+          }
+
+          if (isGroup && groupChannel) {
+            const parsed = parseChannelNest(groupChannel);
+            if (!parsed) {
+              return;
+            }
+            await sendGroupMessage({
+              api: api,
+              fromShip: botShipName,
+              hostShip: parsed.hostShip,
+              channelName: parsed.channelName,
+              text: replyText,
+              replyToId: parentId ?? undefined,
+            });
+          } else {
+            await sendDm({ api: api, fromShip: botShipName, toShip: senderShip, text: replyText });
+          }
+        },
+        onError: (err, info) => {
+          const dispatchDuration = Date.now() - dispatchStartTime;
+          runtime.error?.(
+            `[tlon] ${info.kind} reply failed after ${dispatchDuration}ms: ${String(err)}`,
+          );
+        },
+      },
+      replyOptions: {
+        onModelSelected,
+      },
+    });
+  };
+
+  const subscribedChannels = new Set<string>();
+  const subscribedDMs = new Set<string>();
+
+  async function subscribeToChannel(channelNest: string) {
+    if (subscribedChannels.has(channelNest)) {
+      return;
+    }
+    const parsed = parseChannelNest(channelNest);
+    if (!parsed) {
+      runtime.error?.(`[tlon] Invalid channel format: ${channelNest}`);
+      return;
+    }
+
+    try {
+      await api!.subscribe({
+        app: "channels",
+        path: `/${channelNest}`,
+        event: (data: unknown) => {
+          handleIncomingGroupMessage(channelNest)(data as UrbitUpdate);
+        },
+        err: (error) => {
+          runtime.error?.(`[tlon] Group subscription error for ${channelNest}: ${String(error)}`);
+        },
+        quit: () => {
+          runtime.log?.(`[tlon] Group subscription ended for ${channelNest}`);
+          subscribedChannels.delete(channelNest);
+        },
+      });
+      subscribedChannels.add(channelNest);
+      runtime.log?.(`[tlon] Subscribed to group channel: ${channelNest}`);
+    } catch (error) {
+      runtime.error?.(`[tlon] Failed to subscribe to ${channelNest}: ${formatError(error)}`);
+    }
+  }
+
+  async function subscribeToDM(dmShip: string) {
+    if (subscribedDMs.has(dmShip)) {
+      return;
+    }
+    try {
+      await api!.subscribe({
+        app: "chat",
+        path: `/dm/${dmShip}`,
+        event: (data: unknown) => {
+          handleIncomingDM(data as UrbitUpdate);
+        },
+        err: (error) => {
+          runtime.error?.(`[tlon] DM subscription error for ${dmShip}: ${String(error)}`);
+        },
+        quit: () => {
+          runtime.log?.(`[tlon] DM subscription ended for ${dmShip}`);
+          subscribedDMs.delete(dmShip);
+        },
+      });
+      subscribedDMs.add(dmShip);
+      runtime.log?.(`[tlon] Subscribed to DM with ${dmShip}`);
+    } catch (error) {
+      runtime.error?.(`[tlon] Failed to subscribe to DM with ${dmShip}: ${formatError(error)}`);
+    }
+  }
+
+  async function refreshChannelSubscriptions() {
+    try {
+      const dmShips = await api!.scry("/chat/dm.json");
+      if (Array.isArray(dmShips)) {
+        for (const dmShip of dmShips) {
+          await subscribeToDM(dmShip);
+        }
+      }
+
+      if (account.autoDiscoverChannels !== false) {
+        const discoveredChannels = await fetchAllChannels(api!, runtime);
+        for (const channelNest of discoveredChannels) {
+          await subscribeToChannel(channelNest);
+        }
+      }
+    } catch (error) {
+      runtime.error?.(`[tlon] Channel refresh failed: ${formatError(error)}`);
+    }
+  }
+
+  try {
+    runtime.log?.("[tlon] Subscribing to updates...");
+
+    let dmShips: string[] = [];
+    try {
+      const dmList = await api.scry("/chat/dm.json");
+      if (Array.isArray(dmList)) {
+        dmShips = dmList;
+        runtime.log?.(`[tlon] Found ${dmShips.length} DM conversation(s)`);
+      }
+    } catch (error) {
+      runtime.error?.(`[tlon] Failed to fetch DM list: ${formatError(error)}`);
+    }
+
+    for (const dmShip of dmShips) {
+      await subscribeToDM(dmShip);
+    }
+
+    for (const channelNest of groupChannels) {
+      await subscribeToChannel(channelNest);
+    }
+
+    runtime.log?.("[tlon] All subscriptions registered, connecting to SSE stream...");
+    await api.connect();
+    runtime.log?.("[tlon] Connected! All subscriptions active");
+
+    const pollInterval = setInterval(
+      () => {
+        if (!opts.abortSignal?.aborted) {
+          refreshChannelSubscriptions().catch((error) => {
+            runtime.error?.(`[tlon] Channel refresh error: ${formatError(error)}`);
+          });
+        }
+      },
+      2 * 60 * 1000,
+    );
+
+    if (opts.abortSignal) {
+      const signal = opts.abortSignal;
+      await new Promise((resolve) => {
+        signal.addEventListener(
+          "abort",
+          () => {
+            clearInterval(pollInterval);
+            resolve(null);
+          },
+          { once: true },
+        );
+      });
+    } else {
+      await new Promise(() => {});
+    }
+  } finally {
+    try {
+      await api?.close();
+    } catch (error) {
+      runtime.error?.(`[tlon] Cleanup error: ${formatError(error)}`);
+    }
+  }
+}

openclaw/extensions/tlon/src/monitor/processed-messages.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+import { createProcessedMessageTracker } from "./processed-messages.js";
+
+describe("createProcessedMessageTracker", () => {
+  it("dedupes and evicts oldest entries", () => {
+    const tracker = createProcessedMessageTracker(3);
+
+    expect(tracker.mark("a")).toBe(true);
+    expect(tracker.mark("a")).toBe(false);
+    expect(tracker.has("a")).toBe(true);
+
+    tracker.mark("b");
+    tracker.mark("c");
+    expect(tracker.size()).toBe(3);
+
+    tracker.mark("d");
+    expect(tracker.size()).toBe(3);
+    expect(tracker.has("a")).toBe(false);
+    expect(tracker.has("b")).toBe(true);
+    expect(tracker.has("c")).toBe(true);
+    expect(tracker.has("d")).toBe(true);
+  });
+});

openclaw/extensions/tlon/src/monitor/processed-messages.ts

@@ -0,0 +1,33 @@
+import { createDedupeCache } from "openclaw/plugin-sdk";
+
+export type ProcessedMessageTracker = {
+  mark: (id?: string | null) => boolean;
+  has: (id?: string | null) => boolean;
+  size: () => number;
+};
+
+export function createProcessedMessageTracker(limit = 2000): ProcessedMessageTracker {
+  const dedupe = createDedupeCache({ ttlMs: 0, maxSize: limit });
+
+  const mark = (id?: string | null) => {
+    const trimmed = id?.trim();
+    if (!trimmed) {
+      return true;
+    }
+    return !dedupe.check(trimmed);
+  };
+
+  const has = (id?: string | null) => {
+    const trimmed = id?.trim();
+    if (!trimmed) {
+      return false;
+    }
+    return dedupe.peek(trimmed);
+  };
+
+  return {
+    mark,
+    has,
+    size: () => dedupe.size(),
+  };
+}

openclaw/extensions/tlon/src/monitor/utils.ts

@@ -0,0 +1,106 @@
+import { normalizeShip } from "../targets.js";
+
+export function formatModelName(modelString?: string | null): string {
+  if (!modelString) {
+    return "AI";
+  }
+  const modelName = modelString.includes("/") ? modelString.split("/")[1] : modelString;
+  const modelMappings: Record<string, string> = {
+    "claude-opus-4-6": "Claude Opus 4.6",
+    "claude-opus-4-5": "Claude Opus 4.5",
+    "claude-sonnet-4-5": "Claude Sonnet 4.5",
+    "claude-sonnet-3-5": "Claude Sonnet 3.5",
+    "gpt-4o": "GPT-4o",
+    "gpt-4-turbo": "GPT-4 Turbo",
+    "gpt-4": "GPT-4",
+    "gemini-2.0-flash": "Gemini 2.0 Flash",
+    "gemini-pro": "Gemini Pro",
+  };
+
+  if (modelMappings[modelName]) {
+    return modelMappings[modelName];
+  }
+  return modelName
+    .replace(/-/g, " ")
+    .split(" ")
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ");
+}
+
+export function isBotMentioned(messageText: string, botShipName: string): boolean {
+  if (!messageText || !botShipName) {
+    return false;
+  }
+  const normalizedBotShip = normalizeShip(botShipName);
+  const escapedShip = normalizedBotShip.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const mentionPattern = new RegExp(`(^|\\s)${escapedShip}(?=\\s|$)`, "i");
+  return mentionPattern.test(messageText);
+}
+
+export function isDmAllowed(senderShip: string, allowlist: string[] | undefined): boolean {
+  if (!allowlist || allowlist.length === 0) {
+    return true;
+  }
+  const normalizedSender = normalizeShip(senderShip);
+  return allowlist.map((ship) => normalizeShip(ship)).some((ship) => ship === normalizedSender);
+}
+
+export function extractMessageText(content: unknown): string {
+  if (!content || !Array.isArray(content)) {
+    return "";
+  }
+
+  return (
+    content
+      // oxlint-disable-next-line typescript/no-explicit-any
+      .map((block: any) => {
+        if (block.inline && Array.isArray(block.inline)) {
+          return (
+            block.inline
+              // oxlint-disable-next-line typescript/no-explicit-any
+              .map((item: any) => {
+                if (typeof item === "string") {
+                  return item;
+                }
+                if (item && typeof item === "object") {
+                  if (item.ship) {
+                    return item.ship;
+                  }
+                  if (item.break !== undefined) {
+                    return "\n";
+                  }
+                  if (item.link && item.link.href) {
+                    return item.link.href;
+                  }
+                }
+                return "";
+              })
+              .join("")
+          );
+        }
+        return "";
+      })
+      .join("\n")
+      .trim()
+  );
+}
+
+export function isSummarizationRequest(messageText: string): boolean {
+  const patterns = [
+    /summarize\s+(this\s+)?(channel|chat|conversation)/i,
+    /what\s+did\s+i\s+miss/i,
+    /catch\s+me\s+up/i,
+    /channel\s+summary/i,
+    /tldr/i,
+  ];
+  return patterns.some((pattern) => pattern.test(messageText));
+}
+
+export function formatChangesDate(daysAgo = 5): string {
+  const now = new Date();
+  const targetDate = new Date(now.getTime() - daysAgo * 24 * 60 * 60 * 1000);
+  const year = targetDate.getFullYear();
+  const month = targetDate.getMonth() + 1;
+  const day = targetDate.getDate();
+  return `~${year}.${month}.${day}..20.19.51..9b9d`;
+}

openclaw/extensions/tlon/src/onboarding.ts

@@ -0,0 +1,229 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import {
+  formatDocsLink,
+  promptAccountId,
+  DEFAULT_ACCOUNT_ID,
+  normalizeAccountId,
+  type ChannelOnboardingAdapter,
+  type WizardPrompter,
+} from "openclaw/plugin-sdk";
+import { buildTlonAccountFields } from "./account-fields.js";
+import type { TlonResolvedAccount } from "./types.js";
+import { listTlonAccountIds, resolveTlonAccount } from "./types.js";
+import { isBlockedUrbitHostname, validateUrbitBaseUrl } from "./urbit/base-url.js";
+
+const channel = "tlon" as const;
+
+function isConfigured(account: TlonResolvedAccount): boolean {
+  return Boolean(account.ship && account.url && account.code);
+}
+
+function applyAccountConfig(params: {
+  cfg: OpenClawConfig;
+  accountId: string;
+  input: {
+    name?: string;
+    ship?: string;
+    url?: string;
+    code?: string;
+    allowPrivateNetwork?: boolean;
+    groupChannels?: string[];
+    dmAllowlist?: string[];
+    autoDiscoverChannels?: boolean;
+  };
+}): OpenClawConfig {
+  const { cfg, accountId, input } = params;
+  const useDefault = accountId === DEFAULT_ACCOUNT_ID;
+  const base = cfg.channels?.tlon ?? {};
+  const nextValues = {
+    enabled: true,
+    ...(input.name ? { name: input.name } : {}),
+    ...buildTlonAccountFields(input),
+  };
+
+  if (useDefault) {
+    return {
+      ...cfg,
+      channels: {
+        ...cfg.channels,
+        tlon: {
+          ...base,
+          ...nextValues,
+        },
+      },
+    };
+  }
+
+  return {
+    ...cfg,
+    channels: {
+      ...cfg.channels,
+      tlon: {
+        ...base,
+        enabled: base.enabled ?? true,
+        accounts: {
+          ...(base as { accounts?: Record<string, unknown> }).accounts,
+          [accountId]: {
+            ...(base as { accounts?: Record<string, Record<string, unknown>> }).accounts?.[
+              accountId
+            ],
+            ...nextValues,
+          },
+        },
+      },
+    },
+  };
+}
+
+async function noteTlonHelp(prompter: WizardPrompter): Promise<void> {
+  await prompter.note(
+    [
+      "You need your Urbit ship URL and login code.",
+      "Example URL: https://your-ship-host",
+      "Example ship: ~sampel-palnet",
+      "If your ship URL is on a private network (LAN/localhost), you must explicitly allow it during setup.",
+      `Docs: ${formatDocsLink("/channels/tlon", "channels/tlon")}`,
+    ].join("\n"),
+    "Tlon setup",
+  );
+}
+
+function parseList(value: string): string[] {
+  return value
+    .split(/[\n,;]+/g)
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+export const tlonOnboardingAdapter: ChannelOnboardingAdapter = {
+  channel,
+  getStatus: async ({ cfg }) => {
+    const accountIds = listTlonAccountIds(cfg);
+    const configured =
+      accountIds.length > 0
+        ? accountIds.some((accountId) => isConfigured(resolveTlonAccount(cfg, accountId)))
+        : isConfigured(resolveTlonAccount(cfg, DEFAULT_ACCOUNT_ID));
+
+    return {
+      channel,
+      configured,
+      statusLines: [`Tlon: ${configured ? "configured" : "needs setup"}`],
+      selectionHint: configured ? "configured" : "urbit messenger",
+      quickstartScore: configured ? 1 : 4,
+    };
+  },
+  configure: async ({ cfg, prompter, accountOverrides, shouldPromptAccountIds }) => {
+    const override = accountOverrides[channel]?.trim();
+    const defaultAccountId = DEFAULT_ACCOUNT_ID;
+    let accountId = override ? normalizeAccountId(override) : defaultAccountId;
+
+    if (shouldPromptAccountIds && !override) {
+      accountId = await promptAccountId({
+        cfg,
+        prompter,
+        label: "Tlon",
+        currentId: accountId,
+        listAccountIds: listTlonAccountIds,
+        defaultAccountId,
+      });
+    }
+
+    const resolved = resolveTlonAccount(cfg, accountId);
+    await noteTlonHelp(prompter);
+
+    const ship = await prompter.text({
+      message: "Ship name",
+      placeholder: "~sampel-palnet",
+      initialValue: resolved.ship ?? undefined,
+      validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+    });
+
+    const url = await prompter.text({
+      message: "Ship URL",
+      placeholder: "https://your-ship-host",
+      initialValue: resolved.url ?? undefined,
+      validate: (value) => {
+        const next = validateUrbitBaseUrl(String(value ?? ""));
+        if (!next.ok) {
+          return next.error;
+        }
+        return undefined;
+      },
+    });
+
+    const validatedUrl = validateUrbitBaseUrl(String(url).trim());
+    if (!validatedUrl.ok) {
+      throw new Error(`Invalid URL: ${validatedUrl.error}`);
+    }
+
+    let allowPrivateNetwork = resolved.allowPrivateNetwork ?? false;
+    if (isBlockedUrbitHostname(validatedUrl.hostname)) {
+      allowPrivateNetwork = await prompter.confirm({
+        message:
+          "Ship URL looks like a private/internal host. Allow private network access? (SSRF risk)",
+        initialValue: allowPrivateNetwork,
+      });
+      if (!allowPrivateNetwork) {
+        throw new Error("Refusing private/internal Ship URL without explicit approval");
+      }
+    }
+
+    const code = await prompter.text({
+      message: "Login code",
+      placeholder: "lidlut-tabwed-pillex-ridrup",
+      initialValue: resolved.code ?? undefined,
+      validate: (value) => (String(value ?? "").trim() ? undefined : "Required"),
+    });
+
+    const wantsGroupChannels = await prompter.confirm({
+      message: "Add group channels manually? (optional)",
+      initialValue: false,
+    });
+
+    let groupChannels: string[] | undefined;
+    if (wantsGroupChannels) {
+      const entry = await prompter.text({
+        message: "Group channels (comma-separated)",
+        placeholder: "chat/~host-ship/general, chat/~host-ship/support",
+      });
+      const parsed = parseList(String(entry ?? ""));
+      groupChannels = parsed.length > 0 ? parsed : undefined;
+    }
+
+    const wantsAllowlist = await prompter.confirm({
+      message: "Restrict DMs with an allowlist?",
+      initialValue: false,
+    });
+
+    let dmAllowlist: string[] | undefined;
+    if (wantsAllowlist) {
+      const entry = await prompter.text({
+        message: "DM allowlist (comma-separated ship names)",
+        placeholder: "~zod, ~nec",
+      });
+      const parsed = parseList(String(entry ?? ""));
+      dmAllowlist = parsed.length > 0 ? parsed : undefined;
+    }
+
+    const autoDiscoverChannels = await prompter.confirm({
+      message: "Enable auto-discovery of group channels?",
+      initialValue: resolved.autoDiscoverChannels ?? true,
+    });
+
+    const next = applyAccountConfig({
+      cfg,
+      accountId,
+      input: {
+        ship: String(ship).trim(),
+        url: String(url).trim(),
+        code: String(code).trim(),
+        allowPrivateNetwork,
+        groupChannels,
+        dmAllowlist,
+        autoDiscoverChannels,
+      },
+    });
+
+    return { cfg: next, accountId };
+  },
+};

openclaw/extensions/tlon/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setTlonRuntime(next: PluginRuntime) {
+  runtime = next;
+}
+
+export function getTlonRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("Tlon runtime not initialized");
+  }
+  return runtime;
+}

openclaw/extensions/tlon/src/targets.ts

@@ -0,0 +1,89 @@
+export type TlonTarget =
+  | { kind: "direct"; ship: string }
+  | { kind: "group"; nest: string; hostShip: string; channelName: string };
+
+const SHIP_RE = /^~?[a-z-]+$/i;
+const NEST_RE = /^chat\/([^/]+)\/([^/]+)$/i;
+
+export function normalizeShip(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return trimmed;
+  }
+  return trimmed.startsWith("~") ? trimmed : `~${trimmed}`;
+}
+
+export function parseChannelNest(raw: string): { hostShip: string; channelName: string } | null {
+  const match = NEST_RE.exec(raw.trim());
+  if (!match) {
+    return null;
+  }
+  const hostShip = normalizeShip(match[1]);
+  const channelName = match[2];
+  return { hostShip, channelName };
+}
+
+export function parseTlonTarget(raw?: string | null): TlonTarget | null {
+  const trimmed = raw?.trim();
+  if (!trimmed) {
+    return null;
+  }
+  const withoutPrefix = trimmed.replace(/^tlon:/i, "");
+
+  const dmPrefix = withoutPrefix.match(/^dm[/:](.+)$/i);
+  if (dmPrefix) {
+    return { kind: "direct", ship: normalizeShip(dmPrefix[1]) };
+  }
+
+  const groupPrefix = withoutPrefix.match(/^(group|room)[/:](.+)$/i);
+  if (groupPrefix) {
+    const groupTarget = groupPrefix[2].trim();
+    if (groupTarget.startsWith("chat/")) {
+      const parsed = parseChannelNest(groupTarget);
+      if (!parsed) {
+        return null;
+      }
+      return {
+        kind: "group",
+        nest: `chat/${parsed.hostShip}/${parsed.channelName}`,
+        hostShip: parsed.hostShip,
+        channelName: parsed.channelName,
+      };
+    }
+    const parts = groupTarget.split("/");
+    if (parts.length === 2) {
+      const hostShip = normalizeShip(parts[0]);
+      const channelName = parts[1];
+      return {
+        kind: "group",
+        nest: `chat/${hostShip}/${channelName}`,
+        hostShip,
+        channelName,
+      };
+    }
+    return null;
+  }
+
+  if (withoutPrefix.startsWith("chat/")) {
+    const parsed = parseChannelNest(withoutPrefix);
+    if (!parsed) {
+      return null;
+    }
+    return {
+      kind: "group",
+      nest: `chat/${parsed.hostShip}/${parsed.channelName}`,
+      hostShip: parsed.hostShip,
+      channelName: parsed.channelName,
+    };
+  }
+
+  if (SHIP_RE.test(withoutPrefix)) {
+    return { kind: "direct", ship: normalizeShip(withoutPrefix) };
+  }
+
+  return null;
+}
+
+export function formatTargetHint(): string {
+  return "dm/~sampel-palnet | ~sampel-palnet | chat/~host-ship/channel | group:~host-ship/channel";
+}

openclaw/extensions/tlon/src/types.ts

@@ -0,0 +1,99 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+
+export type TlonResolvedAccount = {
+  accountId: string;
+  name: string | null;
+  enabled: boolean;
+  configured: boolean;
+  ship: string | null;
+  url: string | null;
+  code: string | null;
+  allowPrivateNetwork: boolean | null;
+  groupChannels: string[];
+  dmAllowlist: string[];
+  autoDiscoverChannels: boolean | null;
+  showModelSignature: boolean | null;
+};
+
+export function resolveTlonAccount(
+  cfg: OpenClawConfig,
+  accountId?: string | null,
+): TlonResolvedAccount {
+  const base = cfg.channels?.tlon as
+    | {
+        name?: string;
+        enabled?: boolean;
+        ship?: string;
+        url?: string;
+        code?: string;
+        allowPrivateNetwork?: boolean;
+        groupChannels?: string[];
+        dmAllowlist?: string[];
+        autoDiscoverChannels?: boolean;
+        showModelSignature?: boolean;
+        accounts?: Record<string, Record<string, unknown>>;
+      }
+    | undefined;
+
+  if (!base) {
+    return {
+      accountId: accountId || "default",
+      name: null,
+      enabled: false,
+      configured: false,
+      ship: null,
+      url: null,
+      code: null,
+      allowPrivateNetwork: null,
+      groupChannels: [],
+      dmAllowlist: [],
+      autoDiscoverChannels: null,
+      showModelSignature: null,
+    };
+  }
+
+  const useDefault = !accountId || accountId === "default";
+  const account = useDefault ? base : base.accounts?.[accountId];
+
+  const ship = (account?.ship ?? base.ship ?? null) as string | null;
+  const url = (account?.url ?? base.url ?? null) as string | null;
+  const code = (account?.code ?? base.code ?? null) as string | null;
+  const allowPrivateNetwork = (account?.allowPrivateNetwork ?? base.allowPrivateNetwork ?? null) as
+    | boolean
+    | null;
+  const groupChannels = (account?.groupChannels ?? base.groupChannels ?? []) as string[];
+  const dmAllowlist = (account?.dmAllowlist ?? base.dmAllowlist ?? []) as string[];
+  const autoDiscoverChannels = (account?.autoDiscoverChannels ??
+    base.autoDiscoverChannels ??
+    null) as boolean | null;
+  const showModelSignature = (account?.showModelSignature ?? base.showModelSignature ?? null) as
+    | boolean
+    | null;
+  const configured = Boolean(ship && url && code);
+
+  return {
+    accountId: accountId || "default",
+    name: (account?.name ?? base.name ?? null) as string | null,
+    enabled: (account?.enabled ?? base.enabled ?? true) !== false,
+    configured,
+    ship,
+    url,
+    code,
+    allowPrivateNetwork,
+    groupChannels,
+    dmAllowlist,
+    autoDiscoverChannels,
+    showModelSignature,
+  };
+}
+
+export function listTlonAccountIds(cfg: OpenClawConfig): string[] {
+  const base = cfg.channels?.tlon as
+    | { ship?: string; accounts?: Record<string, Record<string, unknown>> }
+    | undefined;
+  if (!base) {
+    return [];
+  }
+  const accounts = base.accounts ?? {};
+  return [...(base.ship ? ["default"] : []), ...Object.keys(accounts)];
+}

openclaw/extensions/tlon/src/urbit/auth.ssrf.test.ts

@@ -0,0 +1,44 @@
+import type { LookupFn } from "openclaw/plugin-sdk";
+import { SsrFBlockedError } from "openclaw/plugin-sdk";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { authenticate } from "./auth.js";
+
+describe("tlon urbit auth ssrf", () => {
+  beforeEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("blocks private IPs by default", async () => {
+    const mockFetch = vi.fn();
+    vi.stubGlobal("fetch", mockFetch);
+
+    await expect(authenticate("http://127.0.0.1:8080", "code")).rejects.toBeInstanceOf(
+      SsrFBlockedError,
+    );
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  it("allows private IPs when allowPrivateNetwork is enabled", async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      text: async () => "ok",
+      headers: new Headers({
+        "set-cookie": "urbauth-~zod=123; Path=/; HttpOnly",
+      }),
+    });
+    vi.stubGlobal("fetch", mockFetch);
+    const lookupFn = (async () => [{ address: "127.0.0.1", family: 4 }]) as unknown as LookupFn;
+
+    const cookie = await authenticate("http://127.0.0.1:8080", "code", {
+      ssrfPolicy: { allowPrivateNetwork: true },
+      lookupFn,
+    });
+    expect(cookie).toContain("urbauth-~zod=123");
+    expect(mockFetch).toHaveBeenCalled();
+  });
+});

openclaw/extensions/tlon/src/urbit/auth.ts

@@ -0,0 +1,48 @@
+import type { LookupFn, SsrFPolicy } from "openclaw/plugin-sdk";
+import { UrbitAuthError } from "./errors.js";
+import { urbitFetch } from "./fetch.js";
+
+export type UrbitAuthenticateOptions = {
+  ssrfPolicy?: SsrFPolicy;
+  lookupFn?: LookupFn;
+  fetchImpl?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+  timeoutMs?: number;
+};
+
+export async function authenticate(
+  url: string,
+  code: string,
+  options: UrbitAuthenticateOptions = {},
+): Promise<string> {
+  const { response, release } = await urbitFetch({
+    baseUrl: url,
+    path: "/~/login",
+    init: {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({ password: code }).toString(),
+    },
+    ssrfPolicy: options.ssrfPolicy,
+    lookupFn: options.lookupFn,
+    fetchImpl: options.fetchImpl,
+    timeoutMs: options.timeoutMs ?? 15_000,
+    maxRedirects: 3,
+    auditContext: "tlon-urbit-login",
+  });
+
+  try {
+    if (!response.ok) {
+      throw new UrbitAuthError("auth_failed", `Login failed with status ${response.status}`);
+    }
+
+    // Some Urbit setups require the response body to be read before cookie headers finalize.
+    await response.text().catch(() => {});
+    const cookie = response.headers.get("set-cookie");
+    if (!cookie) {
+      throw new UrbitAuthError("missing_cookie", "No authentication cookie received");
+    }
+    return cookie;
+  } finally {
+    await release();
+  }
+}

openclaw/extensions/tlon/src/urbit/base-url.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { validateUrbitBaseUrl } from "./base-url.js";
+
+describe("validateUrbitBaseUrl", () => {
+  it("adds https:// when scheme is missing and strips path/query fragments", () => {
+    const result = validateUrbitBaseUrl("example.com/foo?bar=baz");
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.baseUrl).toBe("https://example.com");
+    expect(result.hostname).toBe("example.com");
+  });
+
+  it("rejects non-http schemes", () => {
+    const result = validateUrbitBaseUrl("file:///etc/passwd");
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error).toContain("http:// or https://");
+  });
+
+  it("rejects embedded credentials", () => {
+    const result = validateUrbitBaseUrl("https://user:pass@example.com");
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error).toContain("credentials");
+  });
+
+  it("normalizes a trailing dot in the hostname for origin construction", () => {
+    const result = validateUrbitBaseUrl("https://example.com./foo");
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.baseUrl).toBe("https://example.com");
+    expect(result.hostname).toBe("example.com");
+  });
+
+  it("preserves port in the normalized origin", () => {
+    const result = validateUrbitBaseUrl("http://example.com:8080/~/login");
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.baseUrl).toBe("http://example.com:8080");
+  });
+});

openclaw/extensions/tlon/src/urbit/base-url.ts

@@ -0,0 +1,57 @@
+import { isBlockedHostnameOrIp } from "openclaw/plugin-sdk";
+
+export type UrbitBaseUrlValidation =
+  | { ok: true; baseUrl: string; hostname: string }
+  | { ok: false; error: string };
+
+function hasScheme(value: string): boolean {
+  return /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(value);
+}
+
+export function validateUrbitBaseUrl(raw: string): UrbitBaseUrlValidation {
+  const trimmed = String(raw ?? "").trim();
+  if (!trimmed) {
+    return { ok: false, error: "Required" };
+  }
+
+  const candidate = hasScheme(trimmed) ? trimmed : `https://${trimmed}`;
+
+  let parsed: URL;
+  try {
+    parsed = new URL(candidate);
+  } catch {
+    return { ok: false, error: "Invalid URL" };
+  }
+
+  if (!["http:", "https:"].includes(parsed.protocol)) {
+    return { ok: false, error: "URL must use http:// or https://" };
+  }
+
+  if (parsed.username || parsed.password) {
+    return { ok: false, error: "URL must not include credentials" };
+  }
+
+  const hostname = parsed.hostname.trim().toLowerCase().replace(/\.$/, "");
+  if (!hostname) {
+    return { ok: false, error: "Invalid hostname" };
+  }
+
+  // Normalize to origin so callers can't smuggle paths/query fragments into the base URL,
+  // and strip a trailing dot from the hostname (DNS root label).
+  const isIpv6 = hostname.includes(":");
+  const host = parsed.port
+    ? `${isIpv6 ? `[${hostname}]` : hostname}:${parsed.port}`
+    : isIpv6
+      ? `[${hostname}]`
+      : hostname;
+
+  return { ok: true, baseUrl: `${parsed.protocol}//${host}`, hostname };
+}
+
+export function isBlockedUrbitHostname(hostname: string): boolean {
+  const normalized = hostname.trim().toLowerCase().replace(/\.$/, "");
+  if (!normalized) {
+    return false;
+  }
+  return isBlockedHostnameOrIp(normalized);
+}

openclaw/extensions/tlon/src/urbit/channel-client.ts

@@ -0,0 +1,158 @@
+import { randomUUID } from "node:crypto";
+import type { LookupFn, SsrFPolicy } from "openclaw/plugin-sdk";
+import { ensureUrbitChannelOpen, pokeUrbitChannel, scryUrbitPath } from "./channel-ops.js";
+import { getUrbitContext, normalizeUrbitCookie } from "./context.js";
+import { urbitFetch } from "./fetch.js";
+
+export type UrbitChannelClientOptions = {
+  ship?: string;
+  ssrfPolicy?: SsrFPolicy;
+  lookupFn?: LookupFn;
+  fetchImpl?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+};
+
+export class UrbitChannelClient {
+  readonly baseUrl: string;
+  readonly cookie: string;
+  readonly ship: string;
+  readonly ssrfPolicy?: SsrFPolicy;
+  readonly lookupFn?: LookupFn;
+  readonly fetchImpl?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+  private channelId: string | null = null;
+
+  constructor(url: string, cookie: string, options: UrbitChannelClientOptions = {}) {
+    const ctx = getUrbitContext(url, options.ship);
+    this.baseUrl = ctx.baseUrl;
+    this.cookie = normalizeUrbitCookie(cookie);
+    this.ship = ctx.ship;
+    this.ssrfPolicy = options.ssrfPolicy;
+    this.lookupFn = options.lookupFn;
+    this.fetchImpl = options.fetchImpl;
+  }
+
+  private get channelPath(): string {
+    const id = this.channelId;
+    if (!id) {
+      throw new Error("Channel not opened");
+    }
+    return `/~/channel/${id}`;
+  }
+
+  async open(): Promise<void> {
+    if (this.channelId) {
+      return;
+    }
+
+    const channelId = `${Math.floor(Date.now() / 1000)}-${randomUUID()}`;
+    this.channelId = channelId;
+
+    try {
+      await ensureUrbitChannelOpen(
+        {
+          baseUrl: this.baseUrl,
+          cookie: this.cookie,
+          ship: this.ship,
+          channelId,
+          ssrfPolicy: this.ssrfPolicy,
+          lookupFn: this.lookupFn,
+          fetchImpl: this.fetchImpl,
+        },
+        {
+          createBody: [],
+          createAuditContext: "tlon-urbit-channel-open",
+        },
+      );
+    } catch (error) {
+      this.channelId = null;
+      throw error;
+    }
+  }
+
+  async poke(params: { app: string; mark: string; json: unknown }): Promise<number> {
+    await this.open();
+    const channelId = this.channelId;
+    if (!channelId) {
+      throw new Error("Channel not opened");
+    }
+    return await pokeUrbitChannel(
+      {
+        baseUrl: this.baseUrl,
+        cookie: this.cookie,
+        ship: this.ship,
+        channelId,
+        ssrfPolicy: this.ssrfPolicy,
+        lookupFn: this.lookupFn,
+        fetchImpl: this.fetchImpl,
+      },
+      { ...params, auditContext: "tlon-urbit-poke" },
+    );
+  }
+
+  async scry(path: string): Promise<unknown> {
+    return await scryUrbitPath(
+      {
+        baseUrl: this.baseUrl,
+        cookie: this.cookie,
+        ssrfPolicy: this.ssrfPolicy,
+        lookupFn: this.lookupFn,
+        fetchImpl: this.fetchImpl,
+      },
+      { path, auditContext: "tlon-urbit-scry" },
+    );
+  }
+
+  async getOurName(): Promise<string> {
+    const { response, release } = await urbitFetch({
+      baseUrl: this.baseUrl,
+      path: "/~/name",
+      init: {
+        method: "GET",
+        headers: { Cookie: this.cookie },
+      },
+      ssrfPolicy: this.ssrfPolicy,
+      lookupFn: this.lookupFn,
+      fetchImpl: this.fetchImpl,
+      timeoutMs: 30_000,
+      auditContext: "tlon-urbit-name",
+    });
+
+    try {
+      if (!response.ok) {
+        throw new Error(`Name request failed: ${response.status}`);
+      }
+      const text = await response.text();
+      return text.trim();
+    } finally {
+      await release();
+    }
+  }
+
+  async close(): Promise<void> {
+    if (!this.channelId) {
+      return;
+    }
+    const channelPath = this.channelPath;
+    this.channelId = null;
+
+    try {
+      const { response, release } = await urbitFetch({
+        baseUrl: this.baseUrl,
+        path: channelPath,
+        init: { method: "DELETE", headers: { Cookie: this.cookie } },
+        ssrfPolicy: this.ssrfPolicy,
+        lookupFn: this.lookupFn,
+        fetchImpl: this.fetchImpl,
+        timeoutMs: 30_000,
+        auditContext: "tlon-urbit-channel-close",
+      });
+      try {
+        void response.body?.cancel();
+      } finally {
+        await release();
+      }
+    } catch {
+      // ignore cleanup errors
+    }
+  }
+}

openclaw/extensions/tlon/src/urbit/channel-ops.ts

@@ -0,0 +1,164 @@
+import type { LookupFn, SsrFPolicy } from "openclaw/plugin-sdk";
+import { UrbitHttpError } from "./errors.js";
+import { urbitFetch } from "./fetch.js";
+
+export type UrbitChannelDeps = {
+  baseUrl: string;
+  cookie: string;
+  ship: string;
+  channelId: string;
+  ssrfPolicy?: SsrFPolicy;
+  lookupFn?: LookupFn;
+  fetchImpl?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+};
+
+export async function pokeUrbitChannel(
+  deps: UrbitChannelDeps,
+  params: { app: string; mark: string; json: unknown; auditContext: string },
+): Promise<number> {
+  const pokeId = Date.now();
+  const pokeData = {
+    id: pokeId,
+    action: "poke",
+    ship: deps.ship,
+    app: params.app,
+    mark: params.mark,
+    json: params.json,
+  };
+
+  const { response, release } = await urbitFetch({
+    baseUrl: deps.baseUrl,
+    path: `/~/channel/${deps.channelId}`,
+    init: {
+      method: "PUT",
+      headers: {
+        "Content-Type": "application/json",
+        Cookie: deps.cookie,
+      },
+      body: JSON.stringify([pokeData]),
+    },
+    ssrfPolicy: deps.ssrfPolicy,
+    lookupFn: deps.lookupFn,
+    fetchImpl: deps.fetchImpl,
+    timeoutMs: 30_000,
+    auditContext: params.auditContext,
+  });
+
+  try {
+    if (!response.ok && response.status !== 204) {
+      const errorText = await response.text().catch(() => "");
+      throw new Error(`Poke failed: ${response.status}${errorText ? ` - ${errorText}` : ""}`);
+    }
+    return pokeId;
+  } finally {
+    await release();
+  }
+}
+
+export async function scryUrbitPath(
+  deps: Pick<UrbitChannelDeps, "baseUrl" | "cookie" | "ssrfPolicy" | "lookupFn" | "fetchImpl">,
+  params: { path: string; auditContext: string },
+): Promise<unknown> {
+  const scryPath = `/~/scry${params.path}`;
+  const { response, release } = await urbitFetch({
+    baseUrl: deps.baseUrl,
+    path: scryPath,
+    init: {
+      method: "GET",
+      headers: { Cookie: deps.cookie },
+    },
+    ssrfPolicy: deps.ssrfPolicy,
+    lookupFn: deps.lookupFn,
+    fetchImpl: deps.fetchImpl,
+    timeoutMs: 30_000,
+    auditContext: params.auditContext,
+  });
+
+  try {
+    if (!response.ok) {
+      throw new Error(`Scry failed: ${response.status} for path ${params.path}`);
+    }
+    return await response.json();
+  } finally {
+    await release();
+  }
+}
+
+export async function createUrbitChannel(
+  deps: UrbitChannelDeps,
+  params: { body: unknown; auditContext: string },
+): Promise<void> {
+  const { response, release } = await urbitFetch({
+    baseUrl: deps.baseUrl,
+    path: `/~/channel/${deps.channelId}`,
+    init: {
+      method: "PUT",
+      headers: {
+        "Content-Type": "application/json",
+        Cookie: deps.cookie,
+      },
+      body: JSON.stringify(params.body),
+    },
+    ssrfPolicy: deps.ssrfPolicy,
+    lookupFn: deps.lookupFn,
+    fetchImpl: deps.fetchImpl,
+    timeoutMs: 30_000,
+    auditContext: params.auditContext,
+  });
+
+  try {
+    if (!response.ok && response.status !== 204) {
+      throw new UrbitHttpError({ operation: "Channel creation", status: response.status });
+    }
+  } finally {
+    await release();
+  }
+}
+
+export async function wakeUrbitChannel(deps: UrbitChannelDeps): Promise<void> {
+  const { response, release } = await urbitFetch({
+    baseUrl: deps.baseUrl,
+    path: `/~/channel/${deps.channelId}`,
+    init: {
+      method: "PUT",
+      headers: {
+        "Content-Type": "application/json",
+        Cookie: deps.cookie,
+      },
+      body: JSON.stringify([
+        {
+          id: Date.now(),
+          action: "poke",
+          ship: deps.ship,
+          app: "hood",
+          mark: "helm-hi",
+          json: "Opening API channel",
+        },
+      ]),
+    },
+    ssrfPolicy: deps.ssrfPolicy,
+    lookupFn: deps.lookupFn,
+    fetchImpl: deps.fetchImpl,
+    timeoutMs: 30_000,
+    auditContext: "tlon-urbit-channel-wake",
+  });
+
+  try {
+    if (!response.ok && response.status !== 204) {
+      throw new UrbitHttpError({ operation: "Channel activation", status: response.status });
+    }
+  } finally {
+    await release();
+  }
+}
+
+export async function ensureUrbitChannelOpen(
+  deps: UrbitChannelDeps,
+  params: { createBody: unknown; createAuditContext: string },
+): Promise<void> {
+  await createUrbitChannel(deps, {
+    body: params.createBody,
+    auditContext: params.createAuditContext,
+  });
+  await wakeUrbitChannel(deps);
+}

openclaw/extensions/tlon/src/urbit/context.ts

@@ -0,0 +1,47 @@
+import type { SsrFPolicy } from "openclaw/plugin-sdk";
+import { validateUrbitBaseUrl } from "./base-url.js";
+import { UrbitUrlError } from "./errors.js";
+
+export type UrbitContext = {
+  baseUrl: string;
+  hostname: string;
+  ship: string;
+};
+
+export function resolveShipFromHostname(hostname: string): string {
+  const trimmed = hostname.trim().toLowerCase().replace(/\.$/, "");
+  if (!trimmed) {
+    return "";
+  }
+  if (trimmed.includes(".")) {
+    return trimmed.split(".")[0] ?? trimmed;
+  }
+  return trimmed;
+}
+
+export function normalizeUrbitShip(ship: string | undefined, hostname: string): string {
+  const raw = ship?.replace(/^~/, "") ?? resolveShipFromHostname(hostname);
+  return raw.trim();
+}
+
+export function normalizeUrbitCookie(cookie: string): string {
+  return cookie.split(";")[0] ?? cookie;
+}
+
+export function getUrbitContext(url: string, ship?: string): UrbitContext {
+  const validated = validateUrbitBaseUrl(url);
+  if (!validated.ok) {
+    throw new UrbitUrlError(validated.error);
+  }
+  return {
+    baseUrl: validated.baseUrl,
+    hostname: validated.hostname,
+    ship: normalizeUrbitShip(ship, validated.hostname),
+  };
+}
+
+export function ssrfPolicyFromAllowPrivateNetwork(
+  allowPrivateNetwork: boolean | null | undefined,
+): SsrFPolicy | undefined {
+  return allowPrivateNetwork ? { allowPrivateNetwork: true } : undefined;
+}

openclaw/extensions/tlon/src/urbit/errors.ts

@@ -0,0 +1,51 @@
+export type UrbitErrorCode =
+  | "invalid_url"
+  | "http_error"
+  | "auth_failed"
+  | "missing_cookie"
+  | "channel_not_open";
+
+export class UrbitError extends Error {
+  readonly code: UrbitErrorCode;
+
+  constructor(code: UrbitErrorCode, message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "UrbitError";
+    this.code = code;
+  }
+}
+
+export class UrbitUrlError extends UrbitError {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super("invalid_url", message, options);
+    this.name = "UrbitUrlError";
+  }
+}
+
+export class UrbitHttpError extends UrbitError {
+  readonly status: number;
+  readonly operation: string;
+  readonly bodyText?: string;
+
+  constructor(params: { operation: string; status: number; bodyText?: string; cause?: unknown }) {
+    const suffix = params.bodyText ? ` - ${params.bodyText}` : "";
+    super("http_error", `${params.operation} failed: ${params.status}${suffix}`, {
+      cause: params.cause,
+    });
+    this.name = "UrbitHttpError";
+    this.status = params.status;
+    this.operation = params.operation;
+    this.bodyText = params.bodyText;
+  }
+}
+
+export class UrbitAuthError extends UrbitError {
+  constructor(
+    code: "auth_failed" | "missing_cookie",
+    message: string,
+    options?: { cause?: unknown },
+  ) {
+    super(code, message, options);
+    this.name = "UrbitAuthError";
+  }
+}

openclaw/extensions/tlon/src/urbit/fetch.ts

@@ -0,0 +1,39 @@
+import type { LookupFn, SsrFPolicy } from "openclaw/plugin-sdk";
+import { fetchWithSsrFGuard } from "openclaw/plugin-sdk";
+import { validateUrbitBaseUrl } from "./base-url.js";
+import { UrbitUrlError } from "./errors.js";
+
+export type UrbitFetchOptions = {
+  baseUrl: string;
+  path: string;
+  init?: RequestInit;
+  ssrfPolicy?: SsrFPolicy;
+  lookupFn?: LookupFn;
+  fetchImpl?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+  timeoutMs?: number;
+  maxRedirects?: number;
+  signal?: AbortSignal;
+  auditContext?: string;
+  pinDns?: boolean;
+};
+
+export async function urbitFetch(params: UrbitFetchOptions) {
+  const validated = validateUrbitBaseUrl(params.baseUrl);
+  if (!validated.ok) {
+    throw new UrbitUrlError(validated.error);
+  }
+
+  const url = new URL(params.path, validated.baseUrl).toString();
+  return await fetchWithSsrFGuard({
+    url,
+    fetchImpl: params.fetchImpl,
+    init: params.init,
+    timeoutMs: params.timeoutMs,
+    maxRedirects: params.maxRedirects,
+    signal: params.signal,
+    policy: params.ssrfPolicy,
+    lookupFn: params.lookupFn,
+    auditContext: params.auditContext,
+    pinDns: params.pinDns,
+  });
+}

openclaw/extensions/tlon/src/urbit/send.test.ts

@@ -0,0 +1,38 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("@urbit/aura", () => ({
+  scot: vi.fn(() => "mocked-ud"),
+  da: {
+    fromUnix: vi.fn(() => 123n),
+  },
+}));
+
+describe("sendDm", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("uses aura v3 helpers for the DM id", async () => {
+    const { sendDm } = await import("./send.js");
+    const aura = await import("@urbit/aura");
+    const scot = vi.mocked(aura.scot);
+    const fromUnix = vi.mocked(aura.da.fromUnix);
+
+    const sentAt = 1_700_000_000_000;
+    vi.spyOn(Date, "now").mockReturnValue(sentAt);
+
+    const poke = vi.fn(async () => ({}));
+
+    const result = await sendDm({
+      api: { poke },
+      fromShip: "~zod",
+      toShip: "~nec",
+      text: "hi",
+    });
+
+    expect(fromUnix).toHaveBeenCalledWith(sentAt);
+    expect(scot).toHaveBeenCalledWith("ud", 123n);
+    expect(poke).toHaveBeenCalledTimes(1);
+    expect(result.messageId).toBe("~zod/mocked-ud");
+  });
+});

openclaw/extensions/tlon/src/urbit/send.ts

@@ -0,0 +1,131 @@
+import { scot, da } from "@urbit/aura";
+
+export type TlonPokeApi = {
+  poke: (params: { app: string; mark: string; json: unknown }) => Promise<unknown>;
+};
+
+type SendTextParams = {
+  api: TlonPokeApi;
+  fromShip: string;
+  toShip: string;
+  text: string;
+};
+
+export async function sendDm({ api, fromShip, toShip, text }: SendTextParams) {
+  const story = [{ inline: [text] }];
+  const sentAt = Date.now();
+  const idUd = scot("ud", da.fromUnix(sentAt));
+  const id = `${fromShip}/${idUd}`;
+
+  const delta = {
+    add: {
+      memo: {
+        content: story,
+        author: fromShip,
+        sent: sentAt,
+      },
+      kind: null,
+      time: null,
+    },
+  };
+
+  const action = {
+    ship: toShip,
+    diff: { id, delta },
+  };
+
+  await api.poke({
+    app: "chat",
+    mark: "chat-dm-action",
+    json: action,
+  });
+
+  return { channel: "tlon", messageId: id };
+}
+
+type SendGroupParams = {
+  api: TlonPokeApi;
+  fromShip: string;
+  hostShip: string;
+  channelName: string;
+  text: string;
+  replyToId?: string | null;
+};
+
+export async function sendGroupMessage({
+  api,
+  fromShip,
+  hostShip,
+  channelName,
+  text,
+  replyToId,
+}: SendGroupParams) {
+  const story = [{ inline: [text] }];
+  const sentAt = Date.now();
+
+  // Format reply ID as @ud (with dots) - required for Tlon to recognize thread replies
+  let formattedReplyId = replyToId;
+  if (replyToId && /^\d+$/.test(replyToId)) {
+    try {
+      formattedReplyId = scot("ud", BigInt(replyToId));
+    } catch {
+      // Fall back to raw ID if formatting fails
+    }
+  }
+
+  const action = {
+    channel: {
+      nest: `chat/${hostShip}/${channelName}`,
+      action: formattedReplyId
+        ? {
+            // Thread reply - needs post wrapper around reply action
+            // ReplyActionAdd takes Memo: {content, author, sent} - no kind/blob/meta
+            post: {
+              reply: {
+                id: formattedReplyId,
+                action: {
+                  add: {
+                    content: story,
+                    author: fromShip,
+                    sent: sentAt,
+                  },
+                },
+              },
+            },
+          }
+        : {
+            // Regular post
+            post: {
+              add: {
+                content: story,
+                author: fromShip,
+                sent: sentAt,
+                kind: "/chat",
+                blob: null,
+                meta: null,
+              },
+            },
+          },
+    },
+  };
+
+  await api.poke({
+    app: "channels",
+    mark: "channel-action-1",
+    json: action,
+  });
+
+  return { channel: "tlon", messageId: `${fromShip}/${sentAt}` };
+}
+
+export function buildMediaText(text: string | undefined, mediaUrl: string | undefined): string {
+  const cleanText = text?.trim() ?? "";
+  const cleanUrl = mediaUrl?.trim() ?? "";
+  if (cleanText && cleanUrl) {
+    return `${cleanText}\n${cleanUrl}`;
+  }
+  if (cleanUrl) {
+    return cleanUrl;
+  }
+  return cleanText;
+}

openclaw/extensions/tlon/src/urbit/sse-client.test.ts

@@ -0,0 +1,44 @@
+import type { LookupFn } from "openclaw/plugin-sdk";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { UrbitSSEClient } from "./sse-client.js";
+
+const mockFetch = vi.fn();
+
+describe("UrbitSSEClient", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", mockFetch);
+    mockFetch.mockReset();
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("sends subscriptions added after connect", async () => {
+    mockFetch.mockResolvedValue({ ok: true, status: 200, text: async () => "" });
+    const lookupFn = (async () => [{ address: "1.1.1.1", family: 4 }]) as unknown as LookupFn;
+
+    const client = new UrbitSSEClient("https://example.com", "urbauth-~zod=123", {
+      lookupFn,
+    });
+    (client as { isConnected: boolean }).isConnected = true;
+
+    await client.subscribe({
+      app: "chat",
+      path: "/dm/~zod",
+      event: () => {},
+    });
+
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    const [url, init] = mockFetch.mock.calls[0];
+    expect(url).toBe(client.channelUrl);
+    expect(init.method).toBe("PUT");
+    const body = JSON.parse(init.body as string);
+    expect(body).toHaveLength(1);
+    expect(body[0]).toMatchObject({
+      action: "subscribe",
+      app: "chat",
+      path: "/dm/~zod",
+    });
+  });
+});

openclaw/extensions/tlon/src/urbit/sse-client.ts

@@ -0,0 +1,431 @@
+import { randomUUID } from "node:crypto";
+import { Readable } from "node:stream";
+import type { LookupFn, SsrFPolicy } from "openclaw/plugin-sdk";
+import { ensureUrbitChannelOpen, pokeUrbitChannel, scryUrbitPath } from "./channel-ops.js";
+import { getUrbitContext, normalizeUrbitCookie } from "./context.js";
+import { urbitFetch } from "./fetch.js";
+
+export type UrbitSseLogger = {
+  log?: (message: string) => void;
+  error?: (message: string) => void;
+};
+
+type UrbitSseOptions = {
+  ship?: string;
+  ssrfPolicy?: SsrFPolicy;
+  lookupFn?: LookupFn;
+  fetchImpl?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+  onReconnect?: (client: UrbitSSEClient) => Promise<void> | void;
+  autoReconnect?: boolean;
+  maxReconnectAttempts?: number;
+  reconnectDelay?: number;
+  maxReconnectDelay?: number;
+  logger?: UrbitSseLogger;
+};
+
+export class UrbitSSEClient {
+  url: string;
+  cookie: string;
+  ship: string;
+  channelId: string;
+  channelUrl: string;
+  subscriptions: Array<{
+    id: number;
+    action: "subscribe";
+    ship: string;
+    app: string;
+    path: string;
+  }> = [];
+  eventHandlers = new Map<
+    number,
+    { event?: (data: unknown) => void; err?: (error: unknown) => void; quit?: () => void }
+  >();
+  aborted = false;
+  streamController: AbortController | null = null;
+  onReconnect: UrbitSseOptions["onReconnect"] | null;
+  autoReconnect: boolean;
+  reconnectAttempts = 0;
+  maxReconnectAttempts: number;
+  reconnectDelay: number;
+  maxReconnectDelay: number;
+  isConnected = false;
+  logger: UrbitSseLogger;
+  ssrfPolicy?: SsrFPolicy;
+  lookupFn?: LookupFn;
+  fetchImpl?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+  streamRelease: (() => Promise<void>) | null = null;
+
+  constructor(url: string, cookie: string, options: UrbitSseOptions = {}) {
+    const ctx = getUrbitContext(url, options.ship);
+    this.url = ctx.baseUrl;
+    this.cookie = normalizeUrbitCookie(cookie);
+    this.ship = ctx.ship;
+    this.channelId = `${Math.floor(Date.now() / 1000)}-${randomUUID()}`;
+    this.channelUrl = new URL(`/~/channel/${this.channelId}`, this.url).toString();
+    this.onReconnect = options.onReconnect ?? null;
+    this.autoReconnect = options.autoReconnect !== false;
+    this.maxReconnectAttempts = options.maxReconnectAttempts ?? 10;
+    this.reconnectDelay = options.reconnectDelay ?? 1000;
+    this.maxReconnectDelay = options.maxReconnectDelay ?? 30000;
+    this.logger = options.logger ?? {};
+    this.ssrfPolicy = options.ssrfPolicy;
+    this.lookupFn = options.lookupFn;
+    this.fetchImpl = options.fetchImpl;
+  }
+
+  async subscribe(params: {
+    app: string;
+    path: string;
+    event?: (data: unknown) => void;
+    err?: (error: unknown) => void;
+    quit?: () => void;
+  }) {
+    const subId = this.subscriptions.length + 1;
+    const subscription = {
+      id: subId,
+      action: "subscribe",
+      ship: this.ship,
+      app: params.app,
+      path: params.path,
+    } as const;
+
+    this.subscriptions.push(subscription);
+    this.eventHandlers.set(subId, { event: params.event, err: params.err, quit: params.quit });
+
+    if (this.isConnected) {
+      try {
+        await this.sendSubscription(subscription);
+      } catch (error) {
+        const handler = this.eventHandlers.get(subId);
+        handler?.err?.(error);
+      }
+    }
+    return subId;
+  }
+
+  private async sendSubscription(subscription: {
+    id: number;
+    action: "subscribe";
+    ship: string;
+    app: string;
+    path: string;
+  }) {
+    const { response, release } = await urbitFetch({
+      baseUrl: this.url,
+      path: `/~/channel/${this.channelId}`,
+      init: {
+        method: "PUT",
+        headers: {
+          "Content-Type": "application/json",
+          Cookie: this.cookie,
+        },
+        body: JSON.stringify([subscription]),
+      },
+      ssrfPolicy: this.ssrfPolicy,
+      lookupFn: this.lookupFn,
+      fetchImpl: this.fetchImpl,
+      timeoutMs: 30_000,
+      auditContext: "tlon-urbit-subscribe",
+    });
+
+    try {
+      if (!response.ok && response.status !== 204) {
+        const errorText = await response.text().catch(() => "");
+        throw new Error(
+          `Subscribe failed: ${response.status}${errorText ? ` - ${errorText}` : ""}`,
+        );
+      }
+    } finally {
+      await release();
+    }
+  }
+
+  async connect() {
+    await ensureUrbitChannelOpen(
+      {
+        baseUrl: this.url,
+        cookie: this.cookie,
+        ship: this.ship,
+        channelId: this.channelId,
+        ssrfPolicy: this.ssrfPolicy,
+        lookupFn: this.lookupFn,
+        fetchImpl: this.fetchImpl,
+      },
+      {
+        createBody: this.subscriptions,
+        createAuditContext: "tlon-urbit-channel-create",
+      },
+    );
+
+    await this.openStream();
+    this.isConnected = true;
+    this.reconnectAttempts = 0;
+  }
+
+  async openStream() {
+    // Use AbortController with manual timeout so we only abort during initial connection,
+    // not after the SSE stream is established and actively streaming.
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 60_000);
+
+    this.streamController = controller;
+
+    const { response, release } = await urbitFetch({
+      baseUrl: this.url,
+      path: `/~/channel/${this.channelId}`,
+      init: {
+        method: "GET",
+        headers: {
+          Accept: "text/event-stream",
+          Cookie: this.cookie,
+        },
+      },
+      ssrfPolicy: this.ssrfPolicy,
+      lookupFn: this.lookupFn,
+      fetchImpl: this.fetchImpl,
+      signal: controller.signal,
+      auditContext: "tlon-urbit-sse-stream",
+    });
+
+    this.streamRelease = release;
+
+    // Clear timeout once connection established (headers received).
+    clearTimeout(timeoutId);
+
+    if (!response.ok) {
+      await release();
+      this.streamRelease = null;
+      throw new Error(`Stream connection failed: ${response.status}`);
+    }
+
+    this.processStream(response.body).catch((error) => {
+      if (!this.aborted) {
+        this.logger.error?.(`Stream error: ${String(error)}`);
+        for (const { err } of this.eventHandlers.values()) {
+          if (err) {
+            err(error);
+          }
+        }
+      }
+    });
+  }
+
+  async processStream(body: ReadableStream<Uint8Array> | Readable | null) {
+    if (!body) {
+      return;
+    }
+    // oxlint-disable-next-line typescript/no-explicit-any
+    const stream = body instanceof ReadableStream ? Readable.fromWeb(body as any) : body;
+    let buffer = "";
+
+    try {
+      for await (const chunk of stream) {
+        if (this.aborted) {
+          break;
+        }
+        buffer += chunk.toString();
+        let eventEnd;
+        while ((eventEnd = buffer.indexOf("\n\n")) !== -1) {
+          const eventData = buffer.substring(0, eventEnd);
+          buffer = buffer.substring(eventEnd + 2);
+          this.processEvent(eventData);
+        }
+      }
+    } finally {
+      if (this.streamRelease) {
+        const release = this.streamRelease;
+        this.streamRelease = null;
+        await release();
+      }
+      this.streamController = null;
+      if (!this.aborted && this.autoReconnect) {
+        this.isConnected = false;
+        this.logger.log?.("[SSE] Stream ended, attempting reconnection...");
+        await this.attemptReconnect();
+      }
+    }
+  }
+
+  processEvent(eventData: string) {
+    const lines = eventData.split("\n");
+    let data: string | null = null;
+
+    for (const line of lines) {
+      if (line.startsWith("data: ")) {
+        data = line.substring(6);
+      }
+    }
+
+    if (!data) {
+      return;
+    }
+
+    try {
+      const parsed = JSON.parse(data) as { id?: number; json?: unknown; response?: string };
+
+      if (parsed.response === "quit") {
+        if (parsed.id) {
+          const handlers = this.eventHandlers.get(parsed.id);
+          if (handlers?.quit) {
+            handlers.quit();
+          }
+        }
+        return;
+      }
+
+      if (parsed.id && this.eventHandlers.has(parsed.id)) {
+        const { event } = this.eventHandlers.get(parsed.id) ?? {};
+        if (event && parsed.json) {
+          event(parsed.json);
+        }
+      } else if (parsed.json) {
+        for (const { event } of this.eventHandlers.values()) {
+          if (event) {
+            event(parsed.json);
+          }
+        }
+      }
+    } catch (error) {
+      this.logger.error?.(`Error parsing SSE event: ${String(error)}`);
+    }
+  }
+
+  async poke(params: { app: string; mark: string; json: unknown }) {
+    return await pokeUrbitChannel(
+      {
+        baseUrl: this.url,
+        cookie: this.cookie,
+        ship: this.ship,
+        channelId: this.channelId,
+        ssrfPolicy: this.ssrfPolicy,
+        lookupFn: this.lookupFn,
+        fetchImpl: this.fetchImpl,
+      },
+      { ...params, auditContext: "tlon-urbit-poke" },
+    );
+  }
+
+  async scry(path: string) {
+    return await scryUrbitPath(
+      {
+        baseUrl: this.url,
+        cookie: this.cookie,
+        ssrfPolicy: this.ssrfPolicy,
+        lookupFn: this.lookupFn,
+        fetchImpl: this.fetchImpl,
+      },
+      { path, auditContext: "tlon-urbit-scry" },
+    );
+  }
+
+  async attemptReconnect() {
+    if (this.aborted || !this.autoReconnect) {
+      this.logger.log?.("[SSE] Reconnection aborted or disabled");
+      return;
+    }
+
+    if (this.reconnectAttempts >= this.maxReconnectAttempts) {
+      this.logger.error?.(
+        `[SSE] Max reconnection attempts (${this.maxReconnectAttempts}) reached. Giving up.`,
+      );
+      return;
+    }
+
+    this.reconnectAttempts += 1;
+    const delay = Math.min(
+      this.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1),
+      this.maxReconnectDelay,
+    );
+
+    this.logger.log?.(
+      `[SSE] Reconnection attempt ${this.reconnectAttempts}/${this.maxReconnectAttempts} in ${delay}ms...`,
+    );
+
+    await new Promise((resolve) => setTimeout(resolve, delay));
+
+    try {
+      this.channelId = `${Math.floor(Date.now() / 1000)}-${randomUUID()}`;
+      this.channelUrl = new URL(`/~/channel/${this.channelId}`, this.url).toString();
+
+      if (this.onReconnect) {
+        await this.onReconnect(this);
+      }
+
+      await this.connect();
+      this.logger.log?.("[SSE] Reconnection successful!");
+    } catch (error) {
+      this.logger.error?.(`[SSE] Reconnection failed: ${String(error)}`);
+      await this.attemptReconnect();
+    }
+  }
+
+  async close() {
+    this.aborted = true;
+    this.isConnected = false;
+    this.streamController?.abort();
+
+    try {
+      const unsubscribes = this.subscriptions.map((sub) => ({
+        id: sub.id,
+        action: "unsubscribe",
+        subscription: sub.id,
+      }));
+
+      {
+        const { response, release } = await urbitFetch({
+          baseUrl: this.url,
+          path: `/~/channel/${this.channelId}`,
+          init: {
+            method: "PUT",
+            headers: {
+              "Content-Type": "application/json",
+              Cookie: this.cookie,
+            },
+            body: JSON.stringify(unsubscribes),
+          },
+          ssrfPolicy: this.ssrfPolicy,
+          lookupFn: this.lookupFn,
+          fetchImpl: this.fetchImpl,
+          timeoutMs: 30_000,
+          auditContext: "tlon-urbit-unsubscribe",
+        });
+        try {
+          void response.body?.cancel();
+        } finally {
+          await release();
+        }
+      }
+
+      {
+        const { response, release } = await urbitFetch({
+          baseUrl: this.url,
+          path: `/~/channel/${this.channelId}`,
+          init: {
+            method: "DELETE",
+            headers: {
+              Cookie: this.cookie,
+            },
+          },
+          ssrfPolicy: this.ssrfPolicy,
+          lookupFn: this.lookupFn,
+          fetchImpl: this.fetchImpl,
+          timeoutMs: 30_000,
+          auditContext: "tlon-urbit-channel-close",
+        });
+        try {
+          void response.body?.cancel();
+        } finally {
+          await release();
+        }
+      }
+    } catch (error) {
+      this.logger.error?.(`Error closing channel: ${String(error)}`);
+    }
+
+    if (this.streamRelease) {
+      const release = this.streamRelease;
+      this.streamRelease = null;
+      await release();
+    }
+  }
+}