@kodelyth/tlon 2026.5.39 → 2026.5.42

package/src/channel.runtime.ts

@@ -0,0 +1,259 @@
+import crypto from "node:crypto";
+import type { ChannelAccountSnapshot } from "klaw/plugin-sdk/channel-contract";
+import type { ChannelOutboundAdapter } from "klaw/plugin-sdk/channel-send-result";
+import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
+import type { ChannelPlugin } from "klaw/plugin-sdk/core";
+import { monitorTlonProvider } from "./monitor/index.js";
+import { tlonSetupWizard } from "./setup-surface.js";
+import {
+  formatTargetHint,
+  normalizeShip,
+  parseTlonTarget,
+  resolveTlonOutboundTarget,
+} from "./targets.js";
+import { configureClient } from "./tlon-api.js";
+import { resolveTlonAccount } from "./types.js";
+import { authenticate } from "./urbit/auth.js";
+import { ssrfPolicyFromDangerouslyAllowPrivateNetwork } from "./urbit/context.js";
+import { urbitFetch } from "./urbit/fetch.js";
+import {
+  buildMediaStory,
+  sendDm,
+  sendDmWithStory,
+  sendGroupMessage,
+  sendGroupMessageWithStory,
+} from "./urbit/send.js";
+import { uploadImageFromUrl } from "./urbit/upload.js";
+
+type ResolvedTlonAccount = ReturnType<typeof resolveTlonAccount>;
+type ConfiguredTlonAccount = ResolvedTlonAccount & {
+  ship: string;
+  url: string;
+  code: string;
+};
+
+async function createHttpPokeApi(params: {
+  url: string;
+  code: string;
+  ship: string;
+  dangerouslyAllowPrivateNetwork?: boolean;
+}) {
+  const ssrfPolicy = ssrfPolicyFromDangerouslyAllowPrivateNetwork(
+    params.dangerouslyAllowPrivateNetwork,
+  );
+  const cookie = await authenticate(params.url, params.code, { ssrfPolicy });
+  const channelId = `${Math.floor(Date.now() / 1000)}-${crypto.randomUUID()}`;
+  const channelPath = `/~/channel/${channelId}`;
+  const shipName = params.ship.replace(/^~/, "");
+
+  return {
+    poke: async (pokeParams: { app: string; mark: string; json: unknown }) => {
+      const pokeId = Date.now();
+      const pokeData = {
+        id: pokeId,
+        action: "poke",
+        ship: shipName,
+        app: pokeParams.app,
+        mark: pokeParams.mark,
+        json: pokeParams.json,
+      };
+
+      const { response, release } = await urbitFetch({
+        baseUrl: params.url,
+        path: channelPath,
+        init: {
+          method: "PUT",
+          headers: {
+            "Content-Type": "application/json",
+            Cookie: cookie.split(";")[0],
+          },
+          body: JSON.stringify([pokeData]),
+        },
+        ssrfPolicy,
+        auditContext: "tlon-poke",
+      });
+
+      try {
+        if (!response.ok && response.status !== 204) {
+          const errorText = await response.text();
+          throw new Error(`Poke failed: ${response.status} - ${errorText}`);
+        }
+
+        return pokeId;
+      } finally {
+        await release();
+      }
+    },
+    delete: async () => {
+      // No-op for HTTP-only client
+    },
+  };
+}
+
+function resolveOutboundContext(params: {
+  cfg: KlawConfig;
+  accountId?: string | null;
+  to: string;
+}) {
+  const account = resolveTlonAccount(params.cfg, params.accountId ?? undefined);
+  if (!account.configured || !account.ship || !account.url || !account.code) {
+    throw new Error("Tlon account not configured");
+  }
+
+  const parsed = parseTlonTarget(params.to);
+  if (!parsed) {
+    throw new Error(`Invalid Tlon target. Use ${formatTargetHint()}`);
+  }
+
+  return { account: account as ConfiguredTlonAccount, parsed };
+}
+
+function resolveReplyId(replyToId?: string | null, threadId?: string | number | null) {
+  return (replyToId ?? threadId) ? String(replyToId ?? threadId) : undefined;
+}
+
+async function withHttpPokeAccountApi<T>(
+  account: ConfiguredTlonAccount,
+  run: (api: Awaited<ReturnType<typeof createHttpPokeApi>>) => Promise<T>,
+) {
+  const api = await createHttpPokeApi({
+    url: account.url,
+    ship: account.ship,
+    code: account.code,
+    dangerouslyAllowPrivateNetwork: account.dangerouslyAllowPrivateNetwork ?? undefined,
+  });
+
+  try {
+    return await run(api);
+  } finally {
+    try {
+      await api.delete();
+    } catch {
+      // ignore cleanup errors
+    }
+  }
+}
+
+export const tlonRuntimeOutbound: ChannelOutboundAdapter = {
+  deliveryMode: "direct",
+  textChunkLimit: 10000,
+  resolveTarget: ({ to }) => resolveTlonOutboundTarget(to),
+  deliveryCapabilities: {
+    durableFinal: {
+      text: true,
+      media: true,
+      replyTo: true,
+      thread: true,
+      messageSendingHooks: true,
+    },
+  },
+  sendText: async ({ cfg, to, text, accountId, replyToId, threadId }) => {
+    const { account, parsed } = resolveOutboundContext({ cfg, accountId, to });
+    return withHttpPokeAccountApi(account, async (api) => {
+      const fromShip = normalizeShip(account.ship);
+      if (parsed.kind === "dm") {
+        return await sendDm({
+          api,
+          fromShip,
+          toShip: parsed.ship,
+          text,
+        });
+      }
+      return await sendGroupMessage({
+        api,
+        fromShip,
+        hostShip: parsed.hostShip,
+        channelName: parsed.channelName,
+        text,
+        replyToId: resolveReplyId(replyToId, threadId),
+      });
+    });
+  },
+  sendMedia: async ({ cfg, to, text, mediaUrl, accountId, replyToId, threadId }) => {
+    const { account, parsed } = resolveOutboundContext({ cfg, accountId, to });
+
+    configureClient({
+      shipUrl: account.url,
+      shipName: account.ship.replace(/^~/, ""),
+      verbose: false,
+      getCode: async () => account.code,
+      dangerouslyAllowPrivateNetwork: account.dangerouslyAllowPrivateNetwork ?? undefined,
+    });
+
+    const uploadedUrl = mediaUrl ? await uploadImageFromUrl(mediaUrl) : undefined;
+    return withHttpPokeAccountApi(account, async (api) => {
+      const fromShip = normalizeShip(account.ship);
+      const story = buildMediaStory(text, uploadedUrl);
+
+      if (parsed.kind === "dm") {
+        return await sendDmWithStory({
+          api,
+          fromShip,
+          toShip: parsed.ship,
+          story,
+          kind: "media",
+        });
+      }
+      return await sendGroupMessageWithStory({
+        api,
+        fromShip,
+        hostShip: parsed.hostShip,
+        channelName: parsed.channelName,
+        story,
+        replyToId: resolveReplyId(replyToId, threadId),
+        kind: "media",
+      });
+    });
+  },
+};
+
+export async function probeTlonAccount(account: ConfiguredTlonAccount) {
+  try {
+    const ssrfPolicy = ssrfPolicyFromDangerouslyAllowPrivateNetwork(
+      account.dangerouslyAllowPrivateNetwork,
+    );
+    const cookie = await authenticate(account.url, account.code, { ssrfPolicy });
+    const { response, release } = await urbitFetch({
+      baseUrl: account.url,
+      path: "/~/name",
+      init: {
+        method: "GET",
+        headers: { Cookie: cookie },
+      },
+      ssrfPolicy,
+      timeoutMs: 30_000,
+      auditContext: "tlon-probe-account",
+    });
+    try {
+      if (!response.ok) {
+        return { ok: false, error: `Name request failed: ${response.status}` };
+      }
+      return { ok: true };
+    } finally {
+      await release();
+    }
+  } catch (error) {
+    return { ok: false, error: (error as { message?: string })?.message ?? String(error) };
+  }
+}
+
+export async function startTlonGatewayAccount(
+  ctx: Parameters<
+    NonNullable<NonNullable<ChannelPlugin<ResolvedTlonAccount>["gateway"]>["startAccount"]>
+  >[0],
+) {
+  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,
+  });
+}
+
+export { tlonSetupWizard };

package/src/channel.ts

@@ -0,0 +1,192 @@
+import { describeAccountSnapshot } from "klaw/plugin-sdk/account-helpers";
+import { DEFAULT_ACCOUNT_ID } from "klaw/plugin-sdk/account-id";
+import { createHybridChannelConfigAdapter } from "klaw/plugin-sdk/channel-config-helpers";
+import { createChatChannelPlugin, type ChannelPlugin } from "klaw/plugin-sdk/channel-core";
+import { createChannelMessageAdapterFromOutbound } from "klaw/plugin-sdk/channel-message";
+import type { ChannelOutboundAdapter } from "klaw/plugin-sdk/channel-send-result";
+import { createLazyRuntimeModule } from "klaw/plugin-sdk/lazy-runtime";
+import { createRuntimeOutboundDelegates } from "klaw/plugin-sdk/outbound-runtime";
+import {
+  createComputedAccountStatusAdapter,
+  createDefaultChannelRuntimeState,
+} from "klaw/plugin-sdk/status-helpers";
+import { tlonChannelConfigSchema } from "./config-schema.js";
+import { tlonDoctor } from "./doctor.js";
+import { resolveTlonOutboundSessionRoute } from "./session-route.js";
+import { createTlonSetupWizardBase, tlonSetupAdapter } from "./setup-core.js";
+import {
+  formatTargetHint,
+  normalizeShip,
+  parseTlonTarget,
+  resolveTlonOutboundTarget,
+} from "./targets.js";
+import { listTlonAccountIds, resolveTlonAccount } from "./types.js";
+
+const TLON_CHANNEL_ID = "tlon" as const;
+
+const loadTlonChannelRuntime = createLazyRuntimeModule(() => import("./channel.runtime.js"));
+
+const tlonSetupWizardProxy = createTlonSetupWizardBase({
+  resolveConfigured: async ({ cfg, accountId }) =>
+    await (
+      await loadTlonChannelRuntime()
+    ).tlonSetupWizard.status.resolveConfigured({
+      cfg,
+      accountId,
+    }),
+  resolveStatusLines: async ({ cfg, accountId, configured }) =>
+    (await (
+      await loadTlonChannelRuntime()
+    ).tlonSetupWizard.status.resolveStatusLines?.({
+      cfg,
+      accountId,
+      configured,
+    })) ?? [],
+  finalize: async (params) =>
+    await (
+      await loadTlonChannelRuntime()
+    ).tlonSetupWizard.finalize!(params),
+}) satisfies NonNullable<ChannelPlugin["setupWizard"]>;
+
+const tlonConfigAdapter = createHybridChannelConfigAdapter({
+  sectionKey: TLON_CHANNEL_ID,
+  listAccountIds: listTlonAccountIds,
+  resolveAccount: resolveTlonAccount,
+  defaultAccountId: () => DEFAULT_ACCOUNT_ID,
+  clearBaseFields: ["ship", "code", "url", "name"],
+  preserveSectionOnDefaultDelete: true,
+  resolveAllowFrom: (account) => account.dmAllowlist,
+  formatAllowFrom: (allowFrom) =>
+    allowFrom.map((entry) => normalizeShip(String(entry))).filter(Boolean),
+});
+
+const tlonChannelOutbound: ChannelOutboundAdapter = {
+  deliveryMode: "direct",
+  textChunkLimit: 10000,
+  resolveTarget: ({ to }) => resolveTlonOutboundTarget(to),
+  deliveryCapabilities: {
+    durableFinal: {
+      text: true,
+      media: true,
+      replyTo: true,
+      thread: true,
+      messageSendingHooks: true,
+    },
+  },
+  ...createRuntimeOutboundDelegates({
+    getRuntime: loadTlonChannelRuntime,
+    sendText: { resolve: (runtime) => runtime.tlonRuntimeOutbound.sendText },
+    sendMedia: { resolve: (runtime) => runtime.tlonRuntimeOutbound.sendMedia },
+  }),
+};
+
+const tlonMessageAdapter = createChannelMessageAdapterFromOutbound({
+  id: TLON_CHANNEL_ID,
+  outbound: tlonChannelOutbound,
+});
+
+export const tlonPlugin = createChatChannelPlugin({
+  base: {
+    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: true,
+      reply: true,
+      threads: true,
+    },
+    setup: tlonSetupAdapter,
+    setupWizard: tlonSetupWizardProxy,
+    reload: { configPrefixes: ["channels.tlon"] },
+    configSchema: tlonChannelConfigSchema,
+    config: {
+      ...tlonConfigAdapter,
+      isConfigured: (account) => account.configured,
+      describeAccount: (account) =>
+        describeAccountSnapshot({
+          account,
+          configured: account.configured,
+          extra: {
+            ship: account.ship,
+            url: account.url,
+          },
+        }),
+    },
+    doctor: tlonDoctor,
+    messaging: {
+      targetPrefixes: ["tlon"],
+      normalizeTarget: (target) => {
+        const parsed = parseTlonTarget(target);
+        if (!parsed) {
+          return target.trim();
+        }
+        if (parsed.kind === "dm") {
+          return parsed.ship;
+        }
+        return parsed.nest;
+      },
+      targetResolver: {
+        looksLikeId: (target) => Boolean(parseTlonTarget(target)),
+        hint: formatTargetHint(),
+      },
+      resolveOutboundSessionRoute: (params) => resolveTlonOutboundSessionRoute(params),
+    },
+    message: tlonMessageAdapter,
+    status: createComputedAccountStatusAdapter<ReturnType<typeof resolveTlonAccount>>({
+      defaultRuntime: createDefaultChannelRuntimeState(DEFAULT_ACCOUNT_ID),
+      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 }) => {
+        const s = snapshot as { configured?: boolean; ship?: string; url?: string };
+        return {
+          configured: s.configured ?? false,
+          ship: s.ship ?? null,
+          url: s.url ?? null,
+        };
+      },
+      probeAccount: async ({ account }) => {
+        if (!account.configured || !account.ship || !account.url || !account.code) {
+          return { ok: false, error: "Not configured" };
+        }
+        return await (await loadTlonChannelRuntime()).probeTlonAccount(account as never);
+      },
+      resolveAccountSnapshot: ({ account }) => ({
+        accountId: account.accountId,
+        name: account.name ?? undefined,
+        enabled: account.enabled,
+        configured: account.configured,
+        extra: {
+          ship: account.ship,
+          url: account.url,
+        },
+      }),
+    }),
+    gateway: {
+      startAccount: async (ctx) =>
+        await (await loadTlonChannelRuntime()).startTlonGatewayAccount(ctx),
+    },
+  },
+  outbound: tlonChannelOutbound,
+});

package/src/config-schema.ts

@@ -0,0 +1,54 @@
+import { buildChannelConfigSchema } from "klaw/plugin-sdk/channel-config-schema";
+import { z } from "zod";
+
+const ShipSchema = z.string().min(1);
+const ChannelNestSchema = z.string().min(1);
+
+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 TlonNetworkSchema = z
+  .object({
+    dangerouslyAllowPrivateNetwork: z.boolean().optional(),
+  })
+  .strict()
+  .optional();
+
+const tlonCommonConfigFields = {
+  name: z.string().optional(),
+  enabled: z.boolean().optional(),
+  ship: ShipSchema.optional(),
+  url: z.string().optional(),
+  code: z.string().optional(),
+  network: TlonNetworkSchema,
+  groupChannels: z.array(ChannelNestSchema).optional(),
+  dmAllowlist: z.array(ShipSchema).optional(),
+  groupInviteAllowlist: z.array(ShipSchema).optional(),
+  autoDiscoverChannels: z.boolean().optional(),
+  showModelSignature: z.boolean().optional(),
+  responsePrefix: z.string().optional(),
+  // Auto-accept settings
+  autoAcceptDmInvites: z.boolean().optional(), // Auto-accept DMs from ships in dmAllowlist
+  autoAcceptGroupInvites: z.boolean().optional(), // Auto-accept all group invites
+  // Owner ship for approval system
+  ownerShip: ShipSchema.optional(), // Ship that receives approval requests and can approve/deny
+} satisfies z.ZodRawShape;
+
+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);