@actagent/tlon 2026.6.2

package/src/channel.ts

@@ -0,0 +1,193 @@
+// Tlon plugin module implements channel behavior.
+import { describeAccountSnapshot } from "actagent/plugin-sdk/account-helpers";
+import { DEFAULT_ACCOUNT_ID } from "actagent/plugin-sdk/account-id";
+import { createHybridChannelConfigAdapter } from "actagent/plugin-sdk/channel-config-helpers";
+import { createChatChannelPlugin, type ChannelPlugin } from "actagent/plugin-sdk/channel-core";
+import { createChannelMessageAdapterFromOutbound } from "actagent/plugin-sdk/channel-outbound";
+import { createRuntimeOutboundDelegates } from "actagent/plugin-sdk/channel-outbound";
+import type { ChannelOutboundAdapter } from "actagent/plugin-sdk/channel-send-result";
+import { createLazyRuntimeModule } from "actagent/plugin-sdk/lazy-runtime";
+import {
+  createComputedAccountStatusAdapter,
+  createDefaultChannelRuntimeState,
+} from "actagent/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,55 @@
+// Tlon helper module supports config schema behavior.
+import { buildChannelConfigSchema } from "actagent/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);

package/src/core.test.ts

@@ -0,0 +1,299 @@
+// Tlon tests cover core plugin behavior.
+import {
+  createPluginSetupWizardConfigure,
+  createPluginSetupWizardStatus,
+  createTestWizardPrompter,
+  runSetupWizardConfigure,
+} from "actagent/plugin-sdk/plugin-test-runtime";
+import type { WizardPrompter } from "actagent/plugin-sdk/plugin-test-runtime";
+import { describe, expect, it, vi } from "vitest";
+import type { ACTAgentConfig } from "../api.js";
+import { TlonAuthorizationSchema, TlonConfigSchema } from "./config-schema.js";
+import { tlonSetupWizard } from "./setup-surface.js";
+import { normalizeShip, resolveTlonOutboundTarget } from "./targets.js";
+import { listTlonAccountIds, resolveTlonAccount } from "./types.js";
+
+const tlonTestPlugin = {
+  id: "tlon",
+  meta: { label: "Tlon" },
+  setupWizard: tlonSetupWizard,
+  config: {
+    listAccountIds: listTlonAccountIds,
+    defaultAccountId: () => "default",
+    resolveAllowFrom: ({ cfg, accountId }: { cfg: ACTAgentConfig; accountId?: string | null }) =>
+      resolveTlonAccount(cfg, accountId).dmAllowlist,
+    formatAllowFrom: ({
+      allowFrom,
+    }: {
+      cfg: ACTAgentConfig;
+      allowFrom: Array<string | number> | undefined | null;
+    }) => {
+      const entries: string[] = [];
+      for (const entry of allowFrom ?? []) {
+        const normalized = normalizeShip(String(entry));
+        if (normalized) {
+          entries.push(normalized);
+        }
+      }
+      return entries;
+    },
+  },
+  setup: {
+    resolveAccountId: ({ accountId }: { cfg: ACTAgentConfig; accountId?: string | null }) =>
+      accountId ?? "default",
+  },
+};
+
+const tlonConfigure = createPluginSetupWizardConfigure(tlonTestPlugin);
+const tlonStatus = createPluginSetupWizardStatus(tlonTestPlugin);
+
+describe("tlon core", () => {
+  it("formats dm allowlist entries through the shared hybrid adapter", () => {
+    expect(
+      tlonTestPlugin.config.formatAllowFrom?.({
+        cfg: {} as ACTAgentConfig,
+        allowFrom: ["zod", " ~nec "],
+      }),
+    ).toEqual(["~zod", "~nec"]);
+  });
+
+  it("returns an empty dm allowlist when the default account is unconfigured", () => {
+    expect(
+      tlonTestPlugin.config.resolveAllowFrom?.({
+        cfg: {} as ACTAgentConfig,
+        accountId: "default",
+      }),
+    ).toStrictEqual([]);
+  });
+
+  it("resolves dm allowlist from the default account", () => {
+    expect(
+      tlonTestPlugin.config.resolveAllowFrom?.({
+        cfg: {
+          channels: {
+            tlon: {
+              ship: "~sampel-palnet",
+              url: "https://urbit.example.com",
+              code: "lidlut-tabwed-pillex-ridrup",
+              dmAllowlist: ["~zod"],
+            },
+          },
+        } as ACTAgentConfig,
+        accountId: "default",
+      }),
+    ).toEqual(["~zod"]);
+  });
+
+  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");
+  });
+
+  it("exposes group invite allowlists in channel config schema", () => {
+    expect(TlonConfigSchema.parse({ groupInviteAllowlist: ["~zod"] }).groupInviteAllowlist).toEqual(
+      ["~zod"],
+    );
+    expect(
+      TlonConfigSchema.parse({
+        accounts: { primary: { groupInviteAllowlist: ["~nec"] } },
+      }).accounts?.primary?.groupInviteAllowlist,
+    ).toEqual(["~nec"]);
+  });
+
+  it("configures ship, auth, and discovery settings", async () => {
+    const prompter = createTestWizardPrompter({
+      text: vi.fn(async ({ message }: { message: string }) => {
+        if (message === "Ship name") {
+          return "sampel-palnet";
+        }
+        if (message === "Ship URL") {
+          return "https://urbit.example.com";
+        }
+        if (message === "Login code") {
+          return "lidlut-tabwed-pillex-ridrup";
+        }
+        if (message === "Group channels (comma-separated)") {
+          return "chat/~host-ship/general, chat/~host-ship/support";
+        }
+        if (message === "DM allowlist (comma-separated ship names)") {
+          return "~zod, nec";
+        }
+        throw new Error(`Unexpected prompt: ${message}`);
+      }) as WizardPrompter["text"],
+      confirm: vi.fn(async ({ message }: { message: string }) => {
+        if (message === "Add group channels manually? (optional)") {
+          return true;
+        }
+        if (message === "Restrict DMs with an allowlist?") {
+          return true;
+        }
+        if (message === "Enable auto-discovery of group channels?") {
+          return true;
+        }
+        return false;
+      }),
+    });
+
+    const result = await runSetupWizardConfigure({
+      configure: tlonConfigure,
+      cfg: {} as ACTAgentConfig,
+      prompter,
+      options: {},
+    });
+
+    expect(result.accountId).toBe("default");
+    expect(result.cfg.channels?.tlon?.enabled).toBe(true);
+    expect(result.cfg.channels?.tlon?.ship).toBe("~sampel-palnet");
+    expect(result.cfg.channels?.tlon?.url).toBe("https://urbit.example.com");
+    expect(result.cfg.channels?.tlon?.code).toBe("lidlut-tabwed-pillex-ridrup");
+    expect(result.cfg.channels?.tlon?.groupChannels).toEqual([
+      "chat/~host-ship/general",
+      "chat/~host-ship/support",
+    ]);
+    expect(result.cfg.channels?.tlon?.dmAllowlist).toEqual(["~zod", "~nec"]);
+    expect(result.cfg.channels?.tlon?.autoDiscoverChannels).toBe(true);
+    expect(result.cfg.channels?.tlon?.network?.dangerouslyAllowPrivateNetwork).toBe(false);
+  });
+
+  it("resolves dm targets to normalized ships", () => {
+    expect(resolveTlonOutboundTarget("dm/sampel-palnet")).toEqual({
+      ok: true,
+      to: "~sampel-palnet",
+    });
+  });
+
+  it("resolves group targets to canonical chat nests", () => {
+    expect(resolveTlonOutboundTarget("group:host-ship/general")).toEqual({
+      ok: true,
+      to: "chat/~host-ship/general",
+    });
+  });
+
+  it("returns a helpful error for invalid targets", () => {
+    const resolved = resolveTlonOutboundTarget("group:bad-target");
+    expect(resolved.ok).toBe(false);
+    if (resolved.ok) {
+      throw new Error("expected invalid target");
+    }
+    expect(resolved.error.message).toMatch(/invalid tlon target/i);
+  });
+
+  it("lists named accounts and the implicit default account", () => {
+    const cfg = {
+      channels: {
+        tlon: {
+          ship: "~zod",
+          accounts: {
+            Work: { ship: "~bus" },
+            alerts: { ship: "~nec" },
+          },
+        },
+      },
+    } as ACTAgentConfig;
+
+    expect(listTlonAccountIds(cfg)).toEqual(["alerts", "default", "work"]);
+  });
+
+  it("merges named account config over channel defaults", () => {
+    const resolved = resolveTlonAccount(
+      {
+        channels: {
+          tlon: {
+            name: "Base",
+            ship: "~zod",
+            url: "https://urbit.example.com",
+            code: "base-code",
+            dmAllowlist: ["~nec"],
+            groupInviteAllowlist: ["~bus"],
+            defaultAuthorizedShips: ["~marzod"],
+            accounts: {
+              Work: {
+                name: "Work",
+                code: "work-code",
+                dmAllowlist: ["~rovnys"],
+              },
+            },
+          },
+        },
+      } as ACTAgentConfig,
+      "work",
+    );
+
+    expect(resolved.accountId).toBe("work");
+    expect(resolved.name).toBe("Work");
+    expect(resolved.ship).toBe("~zod");
+    expect(resolved.url).toBe("https://urbit.example.com");
+    expect(resolved.code).toBe("work-code");
+    expect(resolved.dmAllowlist).toEqual(["~rovnys"]);
+    expect(resolved.groupInviteAllowlist).toEqual(["~bus"]);
+    expect(resolved.defaultAuthorizedShips).toEqual(["~marzod"]);
+    expect(resolved.configured).toBe(true);
+  });
+
+  it("keeps the default account on channel-level config only", () => {
+    const resolved = resolveTlonAccount(
+      {
+        channels: {
+          tlon: {
+            ship: "~zod",
+            url: "https://urbit.example.com",
+            code: "base-code",
+            accounts: {
+              default: {
+                ship: "~ignored",
+                code: "ignored-code",
+              },
+            },
+          },
+        },
+      } as ACTAgentConfig,
+      "default",
+    );
+
+    expect(resolved.ship).toBe("~zod");
+    expect(resolved.code).toBe("base-code");
+  });
+
+  it("setup status labels the selected account", async () => {
+    const status = await tlonStatus({
+      cfg: {
+        channels: {
+          tlon: {
+            ship: "~zod",
+            url: "https://urbit.example.com",
+            code: "base-code",
+            accounts: {
+              work: {},
+            },
+          },
+        },
+      } as ACTAgentConfig,
+      accountOverrides: { tlon: "work" },
+    });
+
+    expect(status.configured).toBe(true);
+    expect(status.statusLines).toEqual(["Tlon (work): configured"]);
+  });
+});

package/src/doctor-contract.ts

@@ -0,0 +1,10 @@
+// Tlon plugin module implements doctor contract behavior.
+import { createLegacyPrivateNetworkDoctorContract } from "actagent/plugin-sdk/ssrf-runtime";
+
+const contract = createLegacyPrivateNetworkDoctorContract({
+  channelKey: "tlon",
+});
+
+export const legacyConfigRules = contract.legacyConfigRules;
+
+export const normalizeCompatibilityConfig = contract.normalizeCompatibilityConfig;

package/src/doctor.test.ts

@@ -0,0 +1,47 @@
+// Tlon tests cover doctor plugin behavior.
+import { describe, expect, it } from "vitest";
+import { tlonDoctor } from "./doctor.js";
+
+function getTlonCompatibilityNormalizer(): NonNullable<
+  typeof tlonDoctor.normalizeCompatibilityConfig
+> {
+  const normalize = tlonDoctor.normalizeCompatibilityConfig;
+  if (!normalize) {
+    throw new Error("Expected tlon doctor to expose normalizeCompatibilityConfig");
+  }
+  return normalize;
+}
+
+describe("tlon doctor", () => {
+  it("normalizes legacy private-network aliases", () => {
+    const normalize = getTlonCompatibilityNormalizer();
+
+    const result = normalize({
+      cfg: {
+        channels: {
+          tlon: {
+            allowPrivateNetwork: true,
+            accounts: {
+              alt: {
+                allowPrivateNetwork: false,
+              },
+            },
+          },
+        },
+      } as never,
+    });
+
+    expect(result.config.channels?.tlon?.network).toEqual({
+      dangerouslyAllowPrivateNetwork: true,
+    });
+    expect(
+      (
+        result.config.channels?.tlon?.accounts?.alt as
+          | { network?: Record<string, unknown> }
+          | undefined
+      )?.network,
+    ).toEqual({
+      dangerouslyAllowPrivateNetwork: false,
+    });
+  });
+});

package/src/doctor.ts

@@ -0,0 +1,11 @@
+// Tlon plugin module implements doctor behavior.
+import type { ChannelDoctorAdapter } from "actagent/plugin-sdk/channel-contract";
+import {
+  legacyConfigRules as TLON_LEGACY_CONFIG_RULES,
+  normalizeCompatibilityConfig as normalizeTlonCompatibilityConfig,
+} from "./doctor-contract.js";
+
+export const tlonDoctor: ChannelDoctorAdapter = {
+  legacyConfigRules: TLON_LEGACY_CONFIG_RULES,
+  normalizeCompatibilityConfig: normalizeTlonCompatibilityConfig,
+};

package/src/logger-runtime.ts

@@ -0,0 +1,2 @@
+// Tlon plugin module implements logger runtime behavior.
+export { createLoggerBackedRuntime } from "actagent/plugin-sdk/runtime";