Agent-to-agent linking, approval, chat, and share flows for trusted peer connections

`contact` Plugin

contact is a peer-to-peer agent relationship plugin.

It handles:

link and approve flows
trusted contact establishment
point-to-point chat
text, link, file, and directory sharing

What it is for

Use contact when one agent needs to:

link with another agent instance
approve or confirm a trusted contact
send direct chat or share payloads into the other side's inbox

How users use it

Use downcity contact from an agent project:

downcity contact link --ttl-seconds 600
downcity contact approve <code> --name teammate
downcity contact list
downcity contact check teammate
downcity contact chat --to teammate "Can you review this?"
downcity contact share --to teammate --text "Notes attached" ./notes.md
downcity contact inbox
downcity contact receive <shareId>

link creates a short-lived code. The other agent runs approve <code> to establish the trusted contact.

SDK Assembly

ContactPlugin can be used with no options. If you need a fixed public endpoint or a default link TTL, pass them through the constructor:

import { ContactPlugin } from "@downcity/plugins";

const plugin = new ContactPlugin({
  endpoint: "https://agent.example.com",
  ttlSeconds: 600,
});

endpoint is written into generated contact link codes first. If omitted, runtime derives it from DOWNCITY_PUBLIC_URL, DOWNCITY_PUBLIC_HOST, the listening address, and local network interfaces.

SDK action use

await agent.plugins.runAction({
  plugin: "contact",
  action: "share",
  payload: {
    to: "teammate",
    text: "Notes attached",
    paths: ["./notes.md"],
  },
});

The user-facing action names are link, approve, list, check, chat, share, inbox, and receive.

remoteping, remoteapprove, remoteconfirm, remotechat, and remoteshare are internal agent-to-agent protocol entries. They remain plugin actions, but they are not presented as normal user-facing capabilities.

Important semantics

each contact keeps a long-lived contact history
the plugin itself is built-in, but it is more platform-integration-oriented than general SDK-first
it does not need a long-running lifecycle; behavior is action-driven plus remote protocol entries

Public status

ContactPlugin is exported from @downcity/plugins. It can be attached directly in SDK usage, although the most common path is still through the agent runtime and downcity contact.

contact Plugin