@actagent/tlon 2026.6.2

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@actagent/tlon",
+  "version": "2026.6.2",
+  "description": "ACTAgent Tlon/Urbit channel plugin for chat workflows.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/actagent/actagent"
+  },
+  "type": "module",
+  "dependencies": {
+    "@aws-sdk/client-s3": "3.1056.0",
+    "@aws-sdk/s3-request-presigner": "3.1056.0",
+    "@tloncorp/tlon-skill": "0.4.0",
+    "@urbit/aura": "3.0.0",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@actagent/plugin-sdk": "workspace:*",
+    "actagent": "workspace:*"
+  },
+  "peerDependencies": {
+    "actagent": "workspace:*"
+  },
+  "peerDependenciesMeta": {
+    "actagent": {
+      "optional": true
+    }
+  },
+  "actagent": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "setupEntry": "./setup-entry.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,
+      "cliAddOptions": [
+        {
+          "flags": "--ship <ship>",
+          "description": "Tlon ship name (~sampel-palnet)"
+        },
+        {
+          "flags": "--code <code>",
+          "description": "Tlon login code"
+        },
+        {
+          "flags": "--group-channels <list>",
+          "description": "Tlon group channels (comma-separated)"
+        },
+        {
+          "flags": "--dm-allowlist <list>",
+          "description": "Tlon DM allowlist (comma-separated ships)"
+        },
+        {
+          "flags": "--auto-discover-channels",
+          "description": "Tlon auto-discover group channels"
+        },
+        {
+          "flags": "--no-auto-discover-channels",
+          "description": "Disable Tlon auto-discovery"
+        }
+      ]
+    },
+    "install": {
+      "npmSpec": "@actagent/tlon",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.4.10"
+    },
+    "compat": {
+      "pluginApi": ">=2026.6.2"
+    },
+    "build": {
+      "actagentVersion": "2026.6.2"
+    },
+    "release": {
+      "bundleRuntimeDependencies": false,
+      "publishToACTAgentHub": true,
+      "publishToNpm": true
+    }
+  }
+}

package/runtime-api.ts

@@ -0,0 +1,17 @@
+// Private runtime barrel for the bundled Tlon extension.
+// Keep this barrel thin and aligned with the local extension surface.
+
+export type { ReplyPayload } from "actagent/plugin-sdk/reply-runtime";
+export type { ACTAgentConfig } from "actagent/plugin-sdk/config-contracts";
+export type { RuntimeEnv } from "actagent/plugin-sdk/runtime";
+export { createDedupeCache } from "actagent/plugin-sdk/core";
+export { createLoggerBackedRuntime } from "./src/logger-runtime.js";
+export {
+  fetchWithSsrFGuard,
+  isBlockedHostnameOrIp,
+  ssrfPolicyFromAllowPrivateNetwork,
+  ssrfPolicyFromDangerouslyAllowPrivateNetwork,
+  type LookupFn,
+  type SsrFPolicy,
+} from "actagent/plugin-sdk/ssrf-runtime";
+export { SsrFBlockedError } from "actagent/plugin-sdk/ssrf-runtime";

package/setup-api.ts

@@ -0,0 +1,3 @@
+// Tlon API module exposes the plugin public contract.
+export { tlonSetupAdapter } from "./src/setup-core.js";
+export { tlonSetupWizard } from "./src/setup-surface.js";

package/setup-entry.ts

@@ -0,0 +1,10 @@
+// Tlon plugin module implements setup entry behavior.
+import { defineBundledChannelSetupEntry } from "actagent/plugin-sdk/channel-entry-contract";
+
+export default defineBundledChannelSetupEntry({
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./api.js",
+    exportName: "tlonPlugin",
+  },
+});

package/src/account-fields.ts

@@ -0,0 +1,32 @@
+// Tlon plugin module implements account fields behavior.
+export type TlonAccountFieldsInput = {
+  ship?: string;
+  url?: string;
+  code?: string;
+  dangerouslyAllowPrivateNetwork?: boolean;
+  groupChannels?: string[];
+  dmAllowlist?: string[];
+  autoDiscoverChannels?: boolean;
+  ownerShip?: string;
+};
+
+export function buildTlonAccountFields(input: TlonAccountFieldsInput) {
+  return {
+    ...(input.ship ? { ship: input.ship } : {}),
+    ...(input.url ? { url: input.url } : {}),
+    ...(input.code ? { code: input.code } : {}),
+    ...(typeof input.dangerouslyAllowPrivateNetwork === "boolean"
+      ? {
+          network: {
+            dangerouslyAllowPrivateNetwork: input.dangerouslyAllowPrivateNetwork,
+          },
+        }
+      : {}),
+    ...(input.groupChannels ? { groupChannels: input.groupChannels } : {}),
+    ...(input.dmAllowlist ? { dmAllowlist: input.dmAllowlist } : {}),
+    ...(typeof input.autoDiscoverChannels === "boolean"
+      ? { autoDiscoverChannels: input.autoDiscoverChannels }
+      : {}),
+    ...(input.ownerShip ? { ownerShip: input.ownerShip } : {}),
+  };
+}

package/src/channel.message-adapter.test.ts

@@ -0,0 +1,147 @@
+// Tlon tests cover channel.message adapter plugin behavior.
+import { verifyChannelMessageAdapterCapabilityProofs } from "actagent/plugin-sdk/channel-outbound";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { ACTAgentConfig } from "../runtime-api.js";
+
+const mocks = vi.hoisted(() => ({
+  sendText: vi.fn(),
+  sendMedia: vi.fn(),
+}));
+
+vi.mock("./channel.runtime.js", () => ({
+  tlonRuntimeOutbound: {
+    sendText: mocks.sendText,
+    sendMedia: mocks.sendMedia,
+  },
+}));
+
+import { tlonPlugin } from "./channel.js";
+
+const cfg = {
+  channels: {
+    tlon: {
+      ship: "~zod",
+      url: "https://zod.example",
+      code: "lidlut-tabwed-pillex-ridrup",
+    },
+  },
+} as ACTAgentConfig;
+
+describe("tlon channel message adapter", () => {
+  beforeEach(() => {
+    mocks.sendText.mockReset();
+    mocks.sendMedia.mockReset();
+    mocks.sendText.mockResolvedValue({
+      channel: "tlon",
+      messageId: "~zod/1700000000000",
+      conversationId: "~nec/general",
+    });
+    mocks.sendMedia.mockResolvedValue({
+      channel: "tlon",
+      messageId: "~zod/1700000000001",
+      conversationId: "~nec/general",
+    });
+  });
+
+  it("backs declared durable-final capabilities with outbound send proofs", async () => {
+    const adapter = tlonPlugin.message;
+    if (!adapter?.send?.text || !adapter.send.media) {
+      throw new Error("expected tlon channel message adapter with text and media senders");
+    }
+    const sendText = adapter.send.text;
+    const sendMedia = adapter.send.media;
+
+    const proveText = async () => {
+      mocks.sendText.mockClear();
+      const result = await sendText({
+        cfg,
+        to: "chat/~nec/general",
+        text: "hello",
+        accountId: "default",
+      });
+      expect(mocks.sendText).toHaveBeenLastCalledWith({
+        cfg,
+        to: "chat/~nec/general",
+        text: "hello",
+        accountId: "default",
+        replyToId: undefined,
+        threadId: undefined,
+      });
+      expect(result.receipt.platformMessageIds).toEqual(["~zod/1700000000000"]);
+      expect(result.receipt.parts[0]?.kind).toBe("text");
+    };
+
+    const proveMedia = async () => {
+      mocks.sendMedia.mockClear();
+      const result = await sendMedia({
+        cfg,
+        to: "chat/~nec/general",
+        text: "image",
+        mediaUrl: "https://example.com/image.png",
+        accountId: "default",
+      });
+      expect(mocks.sendMedia).toHaveBeenLastCalledWith({
+        cfg,
+        to: "chat/~nec/general",
+        text: "image",
+        mediaUrl: "https://example.com/image.png",
+        accountId: "default",
+        replyToId: undefined,
+        threadId: undefined,
+      });
+      expect(result.receipt.platformMessageIds).toEqual(["~zod/1700000000001"]);
+      expect(result.receipt.parts[0]?.kind).toBe("media");
+    };
+
+    const proveReplyThread = async () => {
+      mocks.sendText.mockClear();
+      const result = await sendText({
+        cfg,
+        to: "chat/~nec/general",
+        text: "threaded",
+        accountId: "default",
+        replyToId: "1700000000000",
+        threadId: "1700000000000",
+      });
+      expect(mocks.sendText).toHaveBeenLastCalledWith({
+        cfg,
+        to: "chat/~nec/general",
+        text: "threaded",
+        accountId: "default",
+        replyToId: "1700000000000",
+        threadId: "1700000000000",
+      });
+      expect(result.receipt.replyToId).toBe("1700000000000");
+      expect(result.receipt.threadId).toBe("1700000000000");
+    };
+
+    const proofs = await verifyChannelMessageAdapterCapabilityProofs({
+      adapterName: "tlonMessageAdapter",
+      adapter,
+      proofs: {
+        text: proveText,
+        media: proveMedia,
+        replyTo: proveReplyThread,
+        thread: proveReplyThread,
+        messageSendingHooks: () => {
+          expect(sendText).toBeTypeOf("function");
+        },
+      },
+    });
+    expect(proofs).toStrictEqual([
+      { capability: "text", status: "verified" },
+      { capability: "media", status: "verified" },
+      { capability: "poll", status: "not_declared" },
+      { capability: "payload", status: "not_declared" },
+      { capability: "silent", status: "not_declared" },
+      { capability: "replyTo", status: "verified" },
+      { capability: "thread", status: "verified" },
+      { capability: "nativeQuote", status: "not_declared" },
+      { capability: "messageSendingHooks", status: "verified" },
+      { capability: "batch", status: "not_declared" },
+      { capability: "reconcileUnknownSend", status: "not_declared" },
+      { capability: "afterSendSuccess", status: "not_declared" },
+      { capability: "afterCommit", status: "not_declared" },
+    ]);
+  });
+});

package/src/channel.runtime.ts

@@ -0,0 +1,260 @@
+// Tlon plugin module implements channel behavior.
+import crypto from "node:crypto";
+import type { ChannelAccountSnapshot } from "actagent/plugin-sdk/channel-contract";
+import type { ChannelOutboundAdapter } from "actagent/plugin-sdk/channel-send-result";
+import type { ACTAgentConfig } from "actagent/plugin-sdk/config-contracts";
+import type { ChannelPlugin } from "actagent/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: ACTAgentConfig;
+  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 };