dsh-a2a-groups 0.0.0-stage → 0.1.2

package/lib/core/card.js

@@ -0,0 +1,217 @@
+/**
+ * The A2A agent card: what a peer reads before it sends anything.
+ *
+ * The card is a promise. Every field in it is something the server will honour
+ * or something a peer will branch on, so it is assembled from the same config
+ * and the same skill registry the dispatcher uses — never hand-written. A card
+ * that advertises a skill the dispatcher does not route is worse than no card at
+ * all: the peer discovers it, calls it, and gets `-32601`.
+ *
+ * Boundaries:
+ * - No HTTP. `buildCard()` returns a value; the server decides where to serve it.
+ * - Path constants live here because both the server routes and the card's
+ *   `supportedInterfaces[].url` must agree, and a divergence is silent.
+ *
+ * @module dsh-a2a/card
+ */
+
+import { PROTOCOL_VERSION } from './wire.js';
+
+/** Where the JSON-RPC endpoint lives, relative to the host origin. */
+export const A2A_PATH = '/a2a';
+
+/** The card's canonical location, as A2A 1.0 defines it. */
+export const CARD_PATH = '/a2a/.well-known/agent-card.json';
+
+/**
+ * Legacy alias for the card path.
+ *
+ * 0.3 clients (and a few gateways that never updated) probe `agent.json`. It
+ * costs one route to serve both, and refusing would make a working deployment
+ * look broken to an older peer.
+ */
+export const CARD_ALIAS_PATH = '/a2a/.well-known/agent.json';
+
+/** Media types a 1.0 peer expects on the two input/output mode fields. */
+const DEFAULT_INPUT_MODES = Object.freeze(['text/plain']);
+const DEFAULT_OUTPUT_MODES = Object.freeze(['text/plain']);
+
+/**
+ * The subset of a plugin config the card reads.
+ *
+ * Declared apart from the full §3 config because the card builder needs three
+ * facts only: whether streaming is served at all (it changes what the card
+ * promises), the public endpoint to advertise, and the agent identity strings.
+ * A wider type here would let the card quietly start depending on more config.
+ *
+ * @typedef {object} CardConfig
+ * @property {CardServerConfig} [server] - the server slice of the config.
+ */
+
+/**
+ * The server-config fields the card cares about.
+ *
+ * @typedef {object} CardServerConfig
+ * @property {string} [publicUrl] - fully qualified endpoint; empty means derive from origin.
+ * @property {boolean} [streaming] - whether SendStreamingMessage is served at all.
+ */
+
+/**
+ * One skill as the registry exposes it and the card publishes it.
+ *
+ * Note what is NOT here: the run function. The card is a public JSON document,
+ * so the callable body never travels with it — a peer names the skill id and the
+ * server dispatches. Listing it would either serialize as undefined or leak a
+ * function reference into a document that is served to anyone.
+ *
+ * @typedef {object} CardSkill
+ * @property {string} id - the value a caller puts in message.metadata.skill.
+ * @property {string} [name] - display name; falls back to the id.
+ * @property {string} [description]
+ * @property {string[]} [tags] - free-form grouping, for example a streaming marker.
+ * @property {string[]} [examples] - sample prompts, shown in a discovery UI.
+ * @property {string[]} [inputModes] - defaults to text/plain when absent.
+ * @property {string[]} [outputModes] - defaults to text/plain when absent.
+ */
+
+/**
+ * What the card builder accepts.
+ *
+ * @typedef {object} CardOptions
+ * @property {CardConfig} [config] - normalized plugin config.
+ * @property {{list: () => CardSkill[]}} [skills] - skill registry.
+ * @property {string} [url] - absolute endpoint URL, already ending in /a2a.
+ * @property {string} [name] - agent display name.
+ * @property {string} [description] - agent description.
+ * @property {string} [version] - plugin version.
+ * @property {object} [profile] - layer-B profile extension, or absent.
+ */
+/**
+ * Resolve the public endpoint URL advertised in the card and its interfaces.
+ *
+ * Per §3 of the contract, `config.server.publicUrl` is the *fully qualified*
+ * endpoint a peer should call — an operator behind a gateway writes the whole
+ * `/a2a/me` path there, because only they know what the gateway rewrote. An
+ * empty setting instead means "derive it": the webserver's origin plus `/a2a`,
+ * which is right for a direct bind and for localhost debugging. Appending `/a2a`
+ * to a configured publicUrl would produce `/a2a/me/a2a`, so the two cases are
+ * kept distinct rather than folded into one "base" concept.
+ *
+ * @param {{config?: CardConfig, origin?: () => string|undefined}} input - resolution inputs.
+ * @returns {string} absolute endpoint URL without a trailing slash, or `''` when unknown.
+ */
+export function resolveAgentUrl({ config, origin } = {}) {
+  const configured = typeof config?.server?.publicUrl === 'string' ? config.server.publicUrl.trim() : '';
+  if (configured !== '') return configured.replace(/\/+$/, '');
+  if (typeof origin !== 'function') return '';
+  try {
+    const value = origin();
+    if (typeof value !== 'string' || value.trim() === '') return '';
+    return `${value.trim().replace(/\/+$/, '')}${A2A_PATH}`;
+  } catch {
+    // getOrigin() throws before the listener binds; a card built that early can
+    // still be useful to the operating human, so return an empty url instead.
+    return '';
+  }
+}
+
+/**
+ * Project one registry skill into the card's `skills[]` entry.
+ *
+ * Only declared metadata is copied. `run` is dropped on purpose: the card is a
+ * public document, and shipping a function reference would serialize as
+ * `undefined` in JSON and silently change the shape under test.
+ *
+ * @param {CardSkill} skill - registry skill.
+ * @returns {object|undefined} the card entry, or `undefined` for a malformed skill.
+ */
+export function buildSkillEntry(skill) {
+  if (skill === null || typeof skill !== 'object') return undefined;
+  const id = typeof skill.id === 'string' ? skill.id.trim() : '';
+  if (id === '') return undefined;
+  const entry = {
+    id,
+    name: typeof skill.name === 'string' && skill.name !== '' ? skill.name : id,
+    description: typeof skill.description === 'string' ? skill.description : '',
+  };
+  if (Array.isArray(skill.tags) && skill.tags.length > 0) entry.tags = skill.tags.map(String);
+  if (Array.isArray(skill.examples) && skill.examples.length > 0) entry.examples = skill.examples.map(String);
+  if (Array.isArray(skill.inputModes) && skill.inputModes.length > 0) entry.inputModes = skill.inputModes.map(String);
+  if (Array.isArray(skill.outputModes) && skill.outputModes.length > 0) entry.outputModes = skill.outputModes.map(String);
+  return entry;
+}
+
+/**
+ * Build the agent card document.
+ *
+ * `capabilities` reports what this deployment actually does. `streaming` follows
+ * config because a deployment with streaming off answers `SendStreamingMessage`
+ * with `-32601`, and a card claiming otherwise would make every 1.0 client pick
+ * the wrong method first. `pushNotifications` and `stateTransitionHistory` stay
+ * false: neither is implemented, and a peer that trusts a true here will wait
+ * forever for pushes that never arrive.
+ *
+ * `profile` is the emergent identity (layer B): who this instance is across the
+ * groups it belongs to. It is derived at read time from memberships, so it can
+ * never be stale — which is why it is a parameter here rather than stored state.
+ *
+ * @param {CardOptions} input - card inputs.
+ * @returns {object} the card document, ready to serialize as JSON.
+ */
+export function buildCard({ config, skills, url, name, description, version, profile } = {}) {
+  const endpoint = typeof url === 'string' && url.trim() !== '' ? url.trim().replace(/\/+$/, '') : '';
+  const streaming = config?.server?.streaming !== false;
+  const registrySkills = typeof skills?.list === 'function' ? skills.list() : [];
+  const entries = [];
+  if (Array.isArray(registrySkills)) {
+    for (const skill of registrySkills) {
+      const entry = buildSkillEntry(skill);
+      if (entry !== undefined) entries.push(entry);
+    }
+  }
+  // The profile supplies the identity when the operator did not hard-code one:
+  // `name` falls back to how this person names themselves across groups, and
+  // `description` to an auto-generated line naming their busiest roles.
+  const resolvedName = typeof name === 'string' && name !== ''
+    ? name
+    : (typeof profile?.name === 'string' && profile.name !== '' ? profile.name : 'dsh-a2a');
+  const resolvedDescription = typeof description === 'string' && description !== ''
+    ? description
+    : (typeof profile?.headline === 'string' && profile.headline !== ''
+      ? profile.headline
+      : 'Exposes a DSH Session as an A2A 1.0 agent and carries invite-only collaboration groups.');
+
+  const card = {
+    name: resolvedName,
+    description: resolvedDescription,
+    url: endpoint,
+    version: typeof version === 'string' && version !== '' ? version : '0.1.0',
+    protocolVersion: PROTOCOL_VERSION,
+    preferredTransport: 'JSONRPC',
+    capabilities: {
+      streaming,
+      pushNotifications: false,
+      stateTransitionHistory: false,
+    },
+    defaultInputModes: [...DEFAULT_INPUT_MODES],
+    defaultOutputModes: [...DEFAULT_OUTPUT_MODES],
+    supportedInterfaces: [
+      {
+        url: endpoint,
+        protocolBinding: 'JSONRPC',
+        protocolVersion: PROTOCOL_VERSION,
+      },
+    ],
+    skills: entries,
+  };
+  // Vendor extension, preserved verbatim by an A2A gateway and ignored by a peer
+  // that does not understand it. Carries the per-group identity so a caller can
+  // tell "this is the developer on invoice, the product owner on contracts".
+  if (profile !== undefined && profile !== null && Array.isArray(profile.groups) && profile.groups.length > 0) {
+    const extension = { groups: profile.groups };
+    if (typeof profile.headline === 'string' && profile.headline !== '') extension.headline = profile.headline;
+    if (Array.isArray(profile.tags) && profile.tags.length > 0) extension.tags = profile.tags;
+    card['x-agent-profiles'] = extension;
+  }
+  return card;
+}

package/lib/core/colleague-cards.js

@@ -0,0 +1,149 @@
+/**
+ * Aggregate cached rosters into colleague cards.
+ *
+ * WHY THIS IS ITS OWN MODULE
+ *
+ * It was written inline in `index.js`, where it could only be exercised by mounting the whole
+ * plugin. It is a pure function over data — rosters in, cards out — and the questions worth
+ * testing ("does one person in two groups become two cards?", "does an absent role stay
+ * absent?") have nothing to do with the DSH runtime. Moving it also puts it in `core/`, which
+ * is where the boundary says pure logic belongs.
+ *
+ * WHAT A CARD IS
+ *
+ * A person's own description, collected across every group this instance shares with them:
+ *
+ *   name      the display name they use
+ *   headline  the first role they declared, in group order
+ *   tags      every tag they declared, deduplicated
+ *   roles     all their declared roles, because layer A is per-group
+ *   groups    which of MY groups they are in — a fact the server verified
+ *   online    whether any roster saw them recently
+ *   isSelf    whether this is the reader's own card, which is the only editable one
+ *
+ * WHAT IT REFUSES TO DO
+ *
+ * Invent identity. A tag is self-declared, so a card says "tags", never "department": one
+ * person writing 测试 in one small group does not make them the tester, it makes them
+ * somebody who once took the testing role there. An absent role stays empty rather than
+ * becoming "member", because a placeholder reads as knowledge.
+ *
+ * @module dsh-a2a/colleague-cards
+ */
+
+/** Most cards one snapshot may carry, so a large host cannot inflate every page render. */
+const MAX_CARDS = 100;
+
+/** Most tags per card. A person with forty tags has a data problem, not a profile. */
+const MAX_TAGS = 8;
+
+/** Most roles per card, for the same reason. */
+const MAX_ROLES = 4;
+
+/** Most groups named per card. */
+const MAX_GROUPS = 20;
+
+/**
+ * Build cards from membership records.
+ *
+ * @param {object[]} records - membership records, each possibly carrying a cached `members` roster.
+ * @returns {object[]} cards, most-connected first.
+ */
+export function aggregateColleagueCards(records) {
+  if (!Array.isArray(records)) return [];
+
+  /** personId (or `name:<display>`) → accumulating card. */
+  const byPerson = new Map();
+
+  /**
+   * Which roster rows are mine.
+   *
+   * A membership record names the member id this instance holds in that group, so the row
+   * with the same id is me. Names are a fallback only for a roster that carries no ids at
+   * all, because a display name is not unique.
+   */
+  const selfIds = new Set();
+  const selfNames = new Set();
+  for (const record of records) {
+    if (record === null || typeof record !== 'object') continue;
+    if (typeof record.personId === 'string' && record.personId !== '') selfIds.add(record.personId);
+  }
+
+  for (const record of records) {
+    if (record === null || typeof record !== 'object') continue;
+    const roster = Array.isArray(record.members) ? record.members : [];
+    const groupName = typeof record.groupName === 'string' && record.groupName !== ''
+      ? record.groupName
+      : (typeof record.groupId === 'string' ? record.groupId : '');
+
+    for (const member of roster) {
+      if (member === null || typeof member !== 'object') continue;
+      const name = typeof member.displayName === 'string' ? member.displayName.trim() : '';
+      // A row with no name cannot become a card: "unnamed person" is not a colleague.
+      if (name === '') continue;
+
+      const key = typeof member.personId === 'string' && member.personId !== ''
+        ? member.personId
+        : `name:${name}`;
+
+      let card = byPerson.get(key);
+      if (card === undefined) {
+        card = {
+          personId: typeof member.personId === 'string' ? member.personId : '',
+          name,
+          tags: [],
+          roles: [],
+          groups: [],
+          online: false,
+          // Set from the ledger's own member id, never from the name: two people can share a
+          // display name, and mistaking somebody else's row for mine would offer an edit that
+          // changes the wrong person's profile.
+          isSelf: selfIds.has(member.personId) || (typeof member.personId !== 'string' && selfNames.has(name)),
+        };
+        byPerson.set(key, card);
+      }
+
+      // Any sighting counts: rosters are fetched at different times, and a person seen
+      // online in one group is online.
+      if (member.online === true) card.online = true;
+
+      // Layer A is per-group, so the card keeps the union rather than picking one answer.
+      const about = typeof member.roleAbout === 'string' ? member.roleAbout.trim() : '';
+      if (about !== '' && !card.roles.includes(about)) card.roles.push(about);
+
+      for (const tag of Array.isArray(member.tags) ? member.tags : []) {
+        if (typeof tag === 'string' && tag !== '' && !card.tags.includes(tag)) card.tags.push(tag);
+      }
+
+      if (groupName !== '' && !card.groups.includes(groupName)) card.groups.push(groupName);
+
+      // A roster row that carries my member id confirms which card is mine. Doing it here
+      // rather than only at creation also covers the case where the first roster seen for a
+      // group arrived without ids.
+      if (selfIds.has(member.personId)) card.isSelf = true;
+    }
+  }
+
+  const cards = [...byPerson.values()].map((card) => ({
+    personId: card.personId,
+    name: card.name,
+    isSelf: card.isSelf === true,
+    // The first role they declared. Empty when they never declared one — deliberately not a
+    // placeholder, because a placeholder reads as knowledge.
+    headline: card.roles[0] ?? '',
+    tags: card.tags.slice(0, MAX_TAGS),
+    roles: card.roles.slice(0, MAX_ROLES),
+    groups: card.groups.slice(0, MAX_GROUPS),
+    online: card.online,
+  }));
+
+  // Mine first, always. Every other card is read-only; mine is the one I own, and the
+  // question "what do others see when they look at me" comes before "who else is around".
+  // After that, most connected first — somebody in three of my groups is a likelier target
+  // than somebody I share one group with — with alphabetical ties so the order is stable.
+  cards.sort((left, right) => Number(right.isSelf) - Number(left.isSelf)
+    || right.groups.length - left.groups.length
+    || left.name.localeCompare(right.name));
+
+  return cards.slice(0, MAX_CARDS);
+}

package/lib/core/config.js

@@ -0,0 +1,235 @@
+/**
+ * Configuration for dsh-a2a.
+ *
+ * Config is validated here rather than by a Cordis schema, for the same
+ * self-containment reason as the rest of this plugin: a `Config` export would
+ * require `schemastery`, and a profile plugin is loaded by plain Node
+ * resolution, so bare `@deepseek-ai/...` specifiers would not resolve.
+ *
+ * Every malformed value falls back to its default instead of throwing. A plugin
+ * that refuses to mount because one number was a string is a plugin an operator
+ * cannot diagnose; one that mounts with a logged fallback is one they can.
+ *
+ * @module dsh-a2a/config
+ */
+
+/** Delivery presentations: how an inbound A2A message shows up in a Session. */
+export const PRESENTATIONS = Object.freeze(['notice', 'bubble']);
+
+/** Delivery modes accepted by the deliverer. */
+export const DELIVERY_MODES = Object.freeze(['queue', 'steer', 'interrupt', 'inbox']);
+
+/** The A2A wire versions this plugin speaks. */
+export const PROTOCOL_VERSIONS = Object.freeze(['1.0']);
+
+/** Every default in one place, so a test and an operator read the same numbers. */
+export const DEFAULT_CONFIG = Object.freeze({
+  enabled: true,
+  /**
+   * Identity in the agent card.
+   *
+   * Both fields are OPTIONAL and both have a derived default: with nothing set,
+   * the card names this instance after how it names itself across groups, and
+   * describes it with the roles it declared there (layer B). An operator sets
+   * these only when they want an identity that does not move as memberships
+   * change — which is a legitimate want, not the default.
+   */
+  agent: Object.freeze({
+    name: '',
+    description: '',
+    version: '',
+  }),
+  server: Object.freeze({
+    enabled: true,
+    publicUrl: '',
+    token: '',
+    bindSessionId: 'self',
+    maxBodyBytes: 1048576,
+    taskTimeoutMs: 600000,
+    streaming: true,
+    skills: Object.freeze({ session: true, group: true }),
+  }),
+  client: Object.freeze({
+    enabled: true,
+    apiKey: '',
+    gatewayBase: '',
+    protocolVersion: '1.0',
+    forwardProto: '',
+    cardTtlMs: 300000,
+    timeoutMs: 120000,
+    reconnectAttempts: 3,
+    streamIdleMs: 120000,
+  }),
+  groups: Object.freeze({
+    enabled: true,
+    home: '',
+    // Hours an invite stays valid.
+    //
+    // `null` makes invites permanent by default; a number keeps them bounded. There
+    // is no use counter — revoking a link is how an owner stops it, which is more
+    // precise than waiting for a quota to run out.
+    inviteExpiresInHours: 168,
+    maxPostChars: 32000,
+    maxPostsPerMinute: 20,
+    retentionDays: 30,
+    wakeMembers: true,
+    publicUrl: '',
+    agentName: '',
+    gatewayBase: '',
+    // Whether THIS instance hosts groups itself, instead of a standalone agent-groups
+    // server. Off by default: the normal shape is one shared host behind the gateway
+    // and every DSH instance as a member. Turning it on makes this instance accept
+    // group/create locally, which is only useful for a single-machine setup.
+    embedded: false,
+  }),
+  delivery: Object.freeze({
+    presentation: 'notice',
+    defaultMode: 'queue',
+    hopBudget: 16,
+    dedupeWindowMs: 600000,
+    deliveryTimeoutMs: 120000,
+  }),
+  tools: true,
+  promptSection: true,
+});
+
+/**
+ * Validate and fill in a raw plugin config.
+ *
+ * Unknown keys are dropped: a config that carries a key this version does not
+ * understand is either from a newer release or a typo, and forwarding either
+ * into the runtime would let a typo silently become behaviour.
+ *
+ * @param {object} [raw] - plugin configuration from the profile patch.
+ * @returns {typeof DEFAULT_CONFIG} the normalized settings.
+ */
+export function normalizeConfig(raw) {
+  const source = isPlainObject(raw) ? raw : {};
+  const defaults = DEFAULT_CONFIG;
+  const agent = isPlainObject(source.agent) ? source.agent : {};
+  const server = isPlainObject(source.server) ? source.server : {};
+  const client = isPlainObject(source.client) ? source.client : {};
+  const groups = isPlainObject(source.groups) ? source.groups : {};
+  const delivery = isPlainObject(source.delivery) ? source.delivery : {};
+  const skills = isPlainObject(server.skills) ? server.skills : {};
+
+  return {
+    enabled: bool(source.enabled, defaults.enabled),
+    agent: {
+      name: text(agent.name, defaults.agent.name),
+      description: text(agent.description, defaults.agent.description),
+      version: text(agent.version, defaults.agent.version),
+    },
+    server: {
+      enabled: bool(server.enabled, defaults.server.enabled),
+      publicUrl: text(server.publicUrl, defaults.server.publicUrl),
+      token: text(server.token, defaults.server.token),
+      bindSessionId: text(server.bindSessionId, defaults.server.bindSessionId),
+      maxBodyBytes: integer(server.maxBodyBytes, defaults.server.maxBodyBytes, 1024, 64 * 1024 * 1024),
+      taskTimeoutMs: integer(server.taskTimeoutMs, defaults.server.taskTimeoutMs, 1000, 24 * 3600 * 1000),
+      streaming: bool(server.streaming, defaults.server.streaming),
+      skills: {
+        session: bool(skills.session, defaults.server.skills.session),
+        group: bool(skills.group, defaults.server.skills.group),
+      },
+    },
+    client: {
+      enabled: bool(client.enabled, defaults.client.enabled),
+      apiKey: text(client.apiKey, defaults.client.apiKey),
+      gatewayBase: stripTrailingSlash(text(client.gatewayBase, defaults.client.gatewayBase)),
+      protocolVersion: oneOf(client.protocolVersion, PROTOCOL_VERSIONS, defaults.client.protocolVersion),
+      // Local http development: the gateway advertises `https` on the card unless
+      // a proxy says otherwise, so this header is what makes the card honest.
+      forwardProto: oneOf(text(client.forwardProto, ''), ['', 'http', 'https'], ''),
+      cardTtlMs: integer(client.cardTtlMs, defaults.client.cardTtlMs, 0, 24 * 3600 * 1000),
+      timeoutMs: integer(client.timeoutMs, defaults.client.timeoutMs, 1000, 24 * 3600 * 1000),
+      reconnectAttempts: integer(client.reconnectAttempts, defaults.client.reconnectAttempts, 0, 20),
+      streamIdleMs: integer(client.streamIdleMs, defaults.client.streamIdleMs, 1000, 24 * 3600 * 1000),
+    },
+    groups: {
+      enabled: bool(groups.enabled, defaults.groups.enabled),
+      home: text(groups.home, defaults.groups.home),
+      // `null` = invites never expire by default; a number = that many hours.
+      inviteExpiresInHours: groups.inviteExpiresInHours === null
+        ? null
+        : integer(groups.inviteExpiresInHours, defaults.groups.inviteExpiresInHours, 1, 24 * 365 * 10),
+      maxPostChars: integer(groups.maxPostChars, defaults.groups.maxPostChars, 200, 1024 * 1024),
+      maxPostsPerMinute: integer(groups.maxPostsPerMinute, defaults.groups.maxPostsPerMinute, 1, 10000),
+      retentionDays: integer(groups.retentionDays, defaults.groups.retentionDays, 1, 3650),
+      wakeMembers: bool(groups.wakeMembers, defaults.groups.wakeMembers),
+      publicUrl: stripTrailingSlash(text(groups.publicUrl, defaults.groups.publicUrl)),
+      agentName: text(groups.agentName, defaults.groups.agentName),
+      gatewayBase: stripTrailingSlash(text(groups.gatewayBase, defaults.groups.gatewayBase)),
+      embedded: bool(groups.embedded, defaults.groups.embedded),
+    },
+    delivery: {
+      presentation: oneOf(delivery.presentation, PRESENTATIONS, defaults.delivery.presentation),
+      defaultMode: oneOf(delivery.defaultMode, DELIVERY_MODES, defaults.delivery.defaultMode),
+      hopBudget: integer(delivery.hopBudget, defaults.delivery.hopBudget, 1, 64),
+      dedupeWindowMs: integer(delivery.dedupeWindowMs, defaults.delivery.dedupeWindowMs, 0, 24 * 3600 * 1000),
+      deliveryTimeoutMs: integer(
+        delivery.deliveryTimeoutMs,
+        defaults.delivery.deliveryTimeoutMs,
+        1000,
+        24 * 3600 * 1000,
+      ),
+    },
+    tools: bool(source.tools, defaults.tools),
+    promptSection: bool(source.promptSection, defaults.promptSection),
+  };
+}
+
+/**
+ * The directory that owns this plugin's durable state.
+ *
+ * `<DSH_HOME>/a2a` by default: a plugin's state belongs beside the Sessions it
+ * belongs to, so a profile copied to another machine carries its groups with it.
+ * A configured `groups.home` wins so a deployment can put the state on a shared
+ * volume.
+ *
+ * @param {object} settings - normalized config.
+ * @param {NodeJS.ProcessEnv} [env] - environment to read `DSH_HOME` from.
+ * @returns {string} the state directory.
+ */
+export function resolveHome(settings, env = process.env) {
+  const configured = settings?.groups?.home ?? '';
+  if (configured !== '') return configured;
+  const home = typeof env.DSH_HOME === 'string' && env.DSH_HOME !== '' ? env.DSH_HOME : undefined;
+  const base = home ?? process.cwd();
+  return `${base.replace(/[\\/]+$/, '')}/a2a`;
+}
+
+/** Coerce to a boolean, falling back when absent. */
+function bool(value, fallback) {
+  return typeof value === 'boolean' ? value : fallback;
+}
+
+/** Coerce to a trimmed string, falling back when absent or blank. */
+function text(value, fallback) {
+  if (typeof value !== 'string') return fallback;
+  return value;
+}
+
+/** Coerce to an integer inside `[min, max]`, falling back when unusable. */
+function integer(value, fallback, min, max) {
+  const number = typeof value === 'number' ? value : Number(value);
+  if (!Number.isFinite(number)) return fallback;
+  const rounded = Math.trunc(number);
+  if (rounded < min || rounded > max) return fallback;
+  return rounded;
+}
+
+/** Coerce to one of `allowed`, falling back otherwise. */
+function oneOf(value, allowed, fallback) {
+  return allowed.includes(value) ? value : fallback;
+}
+
+/** Drop trailing slashes so two spellings of the same base compare equal. */
+function stripTrailingSlash(value) {
+  return value.replace(/\/+$/, '');
+}
+
+/** Whether a value is a plain JSON object (not an array, not null). */
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/lib/core/endpoint.js

@@ -0,0 +1,69 @@
+/**
+ * Work out this instance's own A2A address, so a member who joins can be reached.
+ *
+ * THE PROBLEM THIS SOLVES
+ *
+ * The `endpoint` field on a member row has existed since the beginning and has always been empty,
+ * because `join` only took an endpoint the caller passed in — and no caller knows their own
+ * address. So "reach that person directly" was never possible, and the colleague card had no
+ * address to show.
+ *
+ * WHY THE ADDRESS IS COMPOSED, NOT DISCOVERED
+ *
+ * Members reach each other through the gateway, whose convention is already fixed by configuration:
+ *
+ *     <gatewayBase>/<agentName>
+ *     http://gw:3000/a2a/zhangsan
+ *
+ * That is exactly the shape the invite link already encodes (it carries `gw` and `agent`), so
+ * composing it here does not invent a convention — it reuses the one that already lets a colleague
+ * join.
+ *
+ * WHERE IT REFUSES TO GUESS
+ *
+ * When either half is unconfigured, the answer is `undefined`, not a plausible-looking URL. A wrong
+ * endpoint is worse than none: a caller that tries to reach it waits for a timeout and concludes the
+ * whole feature is broken, while an absent one lets the caller say "no address, use the group".
+ *
+ * @module dsh-a2a/endpoint
+ */
+
+/** Characters allowed in one path segment of an agent name. */
+const SAFE_SEGMENT = /^[A-Za-z0-9._~-]+$/u;
+
+/**
+ * Join a base URL and an agent name into an endpoint.
+ *
+ * @param {object} input
+ * @param {string} [input.gatewayBase] the A2A gateway base, e.g. `http://gw:3000/a2a`.
+ * @param {string} [input.agentName] this instance's name at the gateway, e.g. `zhangsan`.
+ * @returns {string|undefined} the endpoint, or undefined when either half is missing.
+ */
+export function composeEndpoint({ gatewayBase, agentName } = {}) {
+  const base = typeof gatewayBase === 'string' ? gatewayBase.trim() : '';
+  const name = typeof agentName === 'string' ? agentName.trim() : '';
+
+  // Both halves are required. Half a URL is not a shorter answer, it is a wrong one.
+  if (base === '' || name === '') return undefined;
+
+  // The name becomes a path segment, so it has to survive being one. A name containing `/` or `?`
+  // would silently truncate or misroute, and the failure would surface as "colleague unreachable"
+  // long after the join that caused it.
+  if (!SAFE_SEGMENT.test(name)) return undefined;
+
+  // A base with a trailing slash and a name with a leading one would produce `//`, which some
+  // gateways treat as a different path.
+  const trimmedBase = base.replace(/\/+$/u, '');
+  return `${trimmedBase}/${name}`;
+}
+
+/**
+ * The endpoint for this host, from its normalized config.
+ *
+ * @param {object} config - normalized config (`config.groups`).
+ * @returns {string|undefined} the endpoint, or undefined when not configured.
+ */
+export function ownEndpointFromConfig(config) {
+  const groups = config?.groups ?? {};
+  return composeEndpoint({ gatewayBase: groups.gatewayBase, agentName: groups.agentName });
+}