dsh-a2a-groups 0.0.0-stage → 0.1.2

package/lib/dsh/profile.js

@@ -0,0 +1,195 @@
+/**
+ * Layer B: the outward-facing profile, aggregated from group memberships.
+ *
+ * The whole point is that nobody maintains this. A person joins groups, says what
+ * they do in each one (layer A), and their card — what any peer reads when it runs
+ * `a2a_discover` — reflects that automatically. Asking people to fill in a profile
+ * form would produce stale text within a month; aggregating from memberships
+ * cannot go stale, because it is derived at read time.
+ *
+ * Two inputs, both already on disk:
+ *
+ *   - `groups.js` knows, for each group this instance hosts, what a member said
+ *     about themselves (`roleAbout` / `tags`).
+ *   - `memberships.js` knows which groups this instance belongs to, with which
+ *     credential, and whether each is local.
+ *
+ * This module is the join of those two, plus the rule that turns them into prose.
+ * It has no I/O of its own: the caller passes the stores in.
+ *
+ * @module dsh-a2a/profile
+ */
+
+/** How many roles to name in the auto-generated one-liner before summarising. */
+const HEADLINE_LIMIT = 3;
+
+/**
+ * Build this instance's profile from its memberships.
+ *
+ * Deterministic and side-effect free, so it can be called on every card read
+ * without cost or surprise: a card is fetched on every `a2a_discover`, and a
+ * profile that did I/O would make discovery slow and failure-prone.
+ *
+ * @param {object} input - sources.
+ * @param {object} [input.identities] - the membership ledger.
+ * @param {object} [input.store] - the group store (for hosted groups' roles).
+ * @param {object} [input.config] - normalized config, for explicit overrides.
+ * @returns {{name: string|undefined, headline: string|undefined, groups: object[], tags: string[]}} the profile.
+ */
+export function buildProfile({ identities, store, config } = {}) {
+  const records = typeof identities?.list === 'function' ? identities.list() : [];
+  const groups = [];
+  /** tag → how many groups declared it. */
+  const tagCounts = new Map();
+  /** displayName → how many groups use it. */
+  const nameCounts = new Map();
+
+  for (const record of records) {
+    const groupId = record.groupId;
+    if (typeof groupId !== 'string' || groupId === '') continue;
+
+    // What this instance said about itself in THAT group. For a hosted group the
+    // store is authoritative; for a joined one only the ledger knows, and it
+    // carries no role detail, so `about` stays empty rather than being invented.
+    const own = ownMembership(store, groupId, record.personId);
+    groups.push({
+      groupId,
+      groupName: own?.groupName ?? record.groupName ?? groupId,
+      roleAbout: own?.roleAbout ?? '',
+      tags: own?.tags ?? [],
+      // The permission bit, carried for completeness: a peer may care whether it
+      // is talking to a group owner, and that is a different fact from the role.
+      permission: own?.role ?? record.role ?? 'member',
+      local: record.local === true,
+    });
+
+    for (const tag of own?.tags ?? []) {
+      tagCounts.set(tag, (tagCounts.get(tag) ?? 0) + 1);
+    }
+    const display = own?.displayName;
+    if (typeof display === 'string' && display !== '') {
+      nameCounts.set(display, (nameCounts.get(display) ?? 0) + 1);
+    }
+  }
+
+  // Most-used tag first; ties broken by the tag itself for a stable order, so two
+  // reads of an unchanged instance produce byte-identical cards.
+  const tags = [...tagCounts.entries()]
+    .sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]))
+    .map(([tag]) => tag);
+
+  const name = pickName({ config, nameCounts, groups });
+  const headline = pickHeadline({ config, tags, groups });
+
+  return { name, headline, groups, tags };
+}
+
+/**
+ * Placeholder display names that should never become an identity.
+ *
+ * These are the values a *tool* fills in when a human did not name themselves:
+ * `owner` and `member` are the store's own defaults, `群主`/`成员` are its Chinese
+ * renderings, and `member-3` is the shape the card client generates. Letting one
+ * of them win the "most common name" vote would put "owner" on the agent card,
+ * which reads as a bug to every peer that sees it.
+ */
+const PLACEHOLDER_NAMES = new Set([
+  'owner', 'member', 'me', 'self', 'user',
+  '群主', '成员', '我', '未知',
+]);
+
+/** Whether a display name carries no real identity. */
+function isPlaceholder(name) {
+  if (typeof name !== 'string') return true;
+  const trimmed = name.trim();
+  if (trimmed === '') return true;
+  if (PLACEHOLDER_NAMES.has(trimmed.toLowerCase())) return true;
+  // `member-1`, `member-12`: generated when a caller supplied no name at all.
+  return /^member-\d+$/.test(trimmed);
+}
+
+/**
+ * What this instance calls itself.
+ *
+ * An explicit `config.agent.name` always wins — an operator may want a stable
+ * identity that does not shift when they join another group. Otherwise the most
+ * common REAL display name across memberships is used. Placeholder names are
+ * skipped: a card that says "owner" tells a peer nothing and looks broken.
+ *
+ * @returns {string|undefined} the name, or undefined when nothing real is known.
+ */
+function pickName({ config, nameCounts, groups }) {
+  const configured = typeof config?.agent?.name === 'string' ? config.agent.name.trim() : '';
+  if (configured !== '') return configured;
+  const ranked = [...nameCounts.entries()]
+    .filter(([name]) => !isPlaceholder(name))
+    .sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]));
+  if (ranked.length > 0) return ranked[0][0];
+  return groups.length > 0 ? undefined : undefined;
+}
+
+/**
+ * One line describing what this instance does, for the card's `description`.
+ *
+ * Three cases, in order of how much is known:
+ *   1. an explicit `config.agent.description` — the operator's own words;
+ *   2. tags exist — name the busiest ones ("主要角色：产品、研发");
+ *   3. nothing declared yet — say plainly that this is a DSH instance, rather
+ *      than emitting an empty string a peer would render as a blank field.
+ */
+function pickHeadline({ config, tags, groups }) {
+  const configured = typeof config?.agent?.description === 'string' ? config.agent.description.trim() : '';
+  if (configured !== '') return configured;
+  if (tags.length > 0) {
+    const named = tags.slice(0, HEADLINE_LIMIT).join('、');
+    const extra = tags.length > HEADLINE_LIMIT ? ` 等 ${tags.length} 类` : '';
+    return `在 ${groups.length} 个协作群里，主要角色：${named}${extra}`;
+  }
+  if (groups.length > 0) {
+    return `在 ${groups.length} 个协作群里，尚未声明角色`;
+  }
+  return undefined;
+}
+
+/**
+ * This instance's own membership in one group, from the group store when hosted.
+ *
+ * Returns `undefined` for a joined group: the ledger records that the membership
+ * exists, not what was declared there. Reading the host's member list to fill that
+ * in would mean a network call inside card rendering — the opposite of what the
+ * card is for.
+ */
+function ownMembership(store, groupId, personId) {
+  if (typeof store?.has !== 'function' || store.has(groupId) !== true) return undefined;
+  if (typeof personId !== 'string' || personId === '') return undefined;
+  try {
+    // `snapshot` is anonymous by design; the self-view needs the credential, which
+    // this module deliberately does not hold. `memberView` (added for exactly this)
+    // answers "what does the store know about member X" without one.
+    if (typeof store.memberView === 'function') return store.memberView({ groupId, personId });
+    return undefined;
+  } catch {
+    // A store that cannot answer must not break the card; the group just shows no
+    // declared role.
+    return undefined;
+  }
+}
+
+/**
+ * The card's extension field carrying the per-group profile.
+ *
+ * Prefix `x-` follows the JSON Schema convention for vendor extensions, and A2A
+ * gateways (AISIX included) preserve unknown card fields verbatim, so a peer that
+ * does not understand this simply ignores it.
+ *
+ * @param {object} profile - the value from {@link buildProfile}.
+ * @returns {object|undefined} the field, or undefined when there is nothing to say.
+ */
+export function profileField(profile) {
+  if (profile === undefined || profile === null) return undefined;
+  if (!Array.isArray(profile.groups) || profile.groups.length === 0) return undefined;
+  const entries = { groups: profile.groups };
+  if (typeof profile.headline === 'string' && profile.headline !== '') entries.headline = profile.headline;
+  if (Array.isArray(profile.tags) && profile.tags.length > 0) entries.tags = profile.tags;
+  return entries;
+}

package/lib/dsh/prompt.js

@@ -0,0 +1,55 @@
+/**
+ * The prompt section: how a Session should behave when it is wired to A2A.
+ *
+ * This text is the only thing that teaches the model *when* to reach for the
+ * A2A tools rather than the local bus, and it is deliberately short. A long
+ * section costs tokens on every turn, and the model has the tool descriptions
+ * one line away; what it cannot infer from a schema is the etiquette (do not
+ * spam a group, close a conversation, ask before broadcasting).
+ *
+ * @module dsh-a2a/prompt
+ */
+
+/** Registry name of this section. */
+export const PROMPT_SECTION_NAME = 'a2a';
+
+/**
+ * Order among other prompt sections.
+ *
+ * Placed after the bus section: a Session that has both should read "prefer the
+ * bus for work on this machine, A2A for other people and other machines", which
+ * only reads that way if the bus rules come first.
+ */
+export const PROMPT_SECTION_ORDER = 620;
+
+/** The section body. Interpolation is off; this is literal text. */
+export const PROMPT_SECTION = `## A2A (other people, other machines)
+
+\`dsh-session-bus\` reaches Sessions **on this machine**. A2A reaches agents
+**behind a gateway** — a colleague's Session, a group, or a third-party agent.
+Pick the bus when the work is local; pick A2A when the work belongs to someone
+else.
+
+**Before sending anywhere**: \`a2a_discover\` the peer and read its skills. Do not
+guess a skill name or a payload shape — a wrong skill is a rejected call, not a
+retryable one.
+
+**Groups are conversation, not broadcast.** A group message wakes every member's
+Session, so it costs everyone a turn. Post when you have something a member
+needs to act on, and answer a group message in the group — not by direct message
+to the person who asked, which leaves the rest of the group blind.
+
+**Close what you open.** When a thread is answered, say so and stop; do not
+send an acknowledgement for every message. If you are told the hop budget is
+exhausted, that means two agents are bouncing: send a conclusion, not another
+question.
+
+**Never invent a recipient.** If \`a2a_agents\` does not list a peer and the user
+did not give you a link or an address, ask for one. Sending a task into an
+unknown agent is worse than asking which agent was meant.
+
+**Group credentials stay out of prose.** An invite link carries a one-time token;
+a group has a password. Do not paste either into a group feed, a Session title,
+or a file that gets committed. If a user asks you to forward an invite, give them
+the link and let them decide where it goes.
+`;

package/lib/dsh/sessions.js

@@ -0,0 +1,278 @@
+/**
+ * Session resolution and turn observation for the A2A server half.
+ *
+ * Two jobs, both about answering "which Session is this agent, and when has it
+ * finished thinking":
+ *
+ *   1. **Binding.** An A2A agent is one DSH instance standing behind one
+ *      Session. The first `session/ask` that arrives can bind it (a Session that
+ *      asks its own instance to become an agent is the ordinary case), or the
+ *      operator names one in config. Both are supported; an unbound agent
+ *      refuses the call instead of silently picking a Session.
+ *
+ *   2. **Turn watching.** `session/ask` has to wait for the *turn* it caused,
+ *      not merely for the delivery call to return — delivery only queues the
+ *      message. The end of a turn is observable on the Host's Session event
+ *      stream, so this module subscribes before delivering and resolves when the
+ *      matching `turn/end` arrives.
+ *
+ * No `@deepseek-ai/*` import: everything Host-specific arrives through `ctx`.
+ *
+ * @module dsh-a2a/sessions
+ */
+
+/** Event names DSH uses for a Session's turn lifecycle, in either vocabulary. */
+const TURN_END_EVENTS = new Set(['turn/end', 'turn-end', 'turnEnd']);
+
+/** Event names that carry what the model said. */
+const ASSISTANT_TEXT_EVENTS = new Set(['assistant/message', 'assistant-message', 'assistantMessage']);
+
+/**
+ * Build the session facade the server and skills share.
+ *
+ * @param {object} options - construction options.
+ * @param {object} options.ctx - plugin context carrying `sessionController`, `sessions`.
+ * @param {object} options.config - normalized config.
+ * @param {object} [options.logger] - host logger.
+ * @param {Function} [options.clock] - epoch-millisecond clock.
+ * @returns {object} the facade.
+ */
+export function createSessions({ ctx, config, logger, clock = () => Date.now() }) {
+  /** Set once something binds this agent to a Session. */
+  let boundSessionId;
+  /** Sessions already offered by a caller, most recent last. */
+  const seen = new Set();
+
+  const controller = () => {
+    const service = ctx?.get?.('sessionController') ?? ctx?.sessionController;
+    if (service === undefined) throw new Error('dsh-a2a: the sessionController service is unavailable in this Host');
+    return service;
+  };
+
+  /**
+   * The Session this agent stands for.
+   *
+   * Config wins when it names one; `'self'` means "the first Session that talks
+   * to me". A configured id is resolved lazily rather than at mount time,
+   * because a Host can mount a plugin before any Session exists.
+   */
+  const resolveBoundSessionId = () => {
+    if (typeof boundSessionId === 'string' && boundSessionId !== '') return boundSessionId;
+    const configured = config?.server?.bindSessionId ?? 'self';
+    if (configured !== 'self') return configured;
+    return undefined;
+  };
+
+  /**
+   * Offer a Session the chance to bind this agent.
+   *
+   * Called from the tool surface, where the calling Session is known. It only
+   * binds while unbound and while config says `self`, so an operator who pinned
+   * a Session cannot have it silently replaced by whoever calls next.
+   *
+   * @param {string} sessionId - the calling Session.
+   * @returns {boolean} true when this call bound it.
+   */
+  const offerBinding = (sessionId) => {
+    if (typeof sessionId !== 'string' || sessionId === '') return false;
+    seen.add(sessionId);
+    if ((config?.server?.bindSessionId ?? 'self') !== 'self') return false;
+    if (typeof boundSessionId === 'string' && boundSessionId !== '') return false;
+    boundSessionId = sessionId;
+    logger?.info?.(`a2a: bound this agent to Session "${sessionId}" (first caller)`);
+    return true;
+  };
+
+  /**
+   * Whether the underlying Agent is currently running a turn.
+   *
+   * Read from the live Agent rather than from the store, so a Session that just
+   * went idle is not reported busy for another polling interval.
+   */
+  const isRunning = (sessionId) => {
+    const agent = liveAgent(sessionId);
+    if (agent === undefined) return false;
+    if (typeof agent.running === 'boolean') return agent.running;
+    const state = agent.state;
+    return state === 'running' || state === 'busy';
+  };
+
+  const liveAgent = (sessionId) => {
+    const agents = ctx?.get?.('agents') ?? ctx?.agents;
+    if (agents !== undefined && typeof agents.get === 'function') {
+      const agent = agents.get(sessionId);
+      if (agent !== undefined && agent !== null) return agent;
+    }
+    const store = ctx?.get?.('sessions') ?? ctx?.sessions;
+    if (store !== undefined && typeof store.get === 'function') {
+      return store.get(sessionId);
+    }
+    return undefined;
+  };
+
+  /**
+   * Watch one Session for the end of the next turn, collecting what it says.
+   *
+   * Subscribing happens before delivery on purpose: delivery can start and even
+   * finish a very fast turn, and a listener attached afterwards would wait
+   * forever for an event that already happened.
+   *
+   * The returned `done` promise never rejects on timeout — it resolves with
+   * `{timedOut:true}`, because a timeout is an outcome the skill reports, not an
+   * exception the transport has to translate.
+   *
+   * @param {string} sessionId - Session to watch.
+   * @param {object} [options] - `{timeoutMs, signal}`.
+   * @returns {{done: Promise<{text: string, events: number, timedOut: boolean}>, cancel: Function}} the watcher.
+   */
+  const watchTurn = (sessionId, options = {}) => {
+    const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : config?.server?.taskTimeoutMs ?? 600000;
+    /** Latest assistant text seen after the turn started. */
+    let text = '';
+    let events = 0;
+    let settled = false;
+    let unsubscribe;
+    let timer;
+
+    const finish = (timedOut) => {
+      if (settled) return;
+      settled = true;
+      if (unsubscribe !== undefined) unsubscribe();
+      if (timer !== undefined) clearTimeout(timer);
+      resolveOutcome({ text, events, timedOut });
+    };
+
+    /** @type {(value: {text: string, events: number, timedOut: boolean}) => void} */
+    let resolveOutcome = () => {};
+    const done = new Promise((resolve) => {
+      resolveOutcome = resolve;
+    });
+
+    const onEvent = (session, event) => {
+      const id = typeof session === 'string' ? session : session?.id;
+      if (id !== sessionId) return;
+      events += 1;
+      const type = event?.type ?? event?.kind;
+      if (typeof type === 'string' && ASSISTANT_TEXT_EVENTS.has(type)) {
+        const candidate = textOfEvent(event);
+        if (candidate !== '') text = candidate;
+        return;
+      }
+      if (typeof type === 'string' && TURN_END_EVENTS.has(type)) {
+        const candidate = textOfEvent(event);
+        if (candidate !== '') text = candidate;
+        finish(false);
+      }
+    };
+
+    unsubscribe = attachEventListener(ctx, onEvent);
+    timer = setTimeout(() => finish(true), timeoutMs);
+    if (typeof timer?.unref === 'function') timer.unref();
+    if (options.signal !== undefined) {
+      const abort = () => finish(true);
+      if (options.signal.aborted) abort();
+      else options.signal.addEventListener('abort', abort, { once: true });
+    }
+
+    return {
+      done,
+      cancel: () => finish(true),
+    };
+  };
+
+  /**
+   * Read the tail of a Session transcript.
+   *
+   * Used by `group/*` skills and the UI to answer "what did this Session say"
+   * without the caller needing the Host's inspection API.
+   *
+   * @param {string} sessionId - Session to read.
+   * @param {number} [limit] - how many messages to return, newest last.
+   * @returns {Promise<Array<{role: string, text: string, at: number}>>} the tail.
+   */
+  const readTail = async (sessionId, limit = 12) => {
+    try {
+      const inspection = await controller().inspect?.(sessionId);
+      const events = Array.isArray(inspection?.events) ? inspection.events : [];
+      const messages = [];
+      for (const event of events.slice(-2000)) {
+        const type = event?.type ?? event?.kind;
+        if (type !== 'user/message' && type !== 'assistant/message') continue;
+        const text = textOfEvent(event);
+        if (text === '') continue;
+        messages.push({ role: type.startsWith('user') ? 'user' : 'assistant', text, at: event.at ?? 0 });
+      }
+      return messages.slice(-Math.max(1, limit));
+    } catch (error) {
+      logger?.warn?.(`a2a: could not read the tail of "${sessionId}": ${describe(error)}`);
+      return [];
+    }
+  };
+
+  return {
+    resolveBoundSessionId,
+    offerBinding,
+    isRunning,
+    watchTurn,
+    readTail,
+    /** For `ping` and the card: what this agent is currently bound to. */
+    info: () => ({ boundSessionId: resolveBoundSessionId() ?? null, candidates: [...seen], now: clock() }),
+  };
+}
+
+/**
+ * Subscribe to Session events however this Host exposes them.
+ *
+ * DSH emits `session/event(session, event)`; older/other compositions expose a
+ * per-session subscription. Both are attempted and the first that exists wins,
+ * so one helper covers a range of Host versions instead of failing shut.
+ *
+ * @param {object} ctx - plugin context.
+ * @param {Function} listener - `(session, event) => void`.
+ * @returns {Function} disposer.
+ */
+function attachEventListener(ctx, listener) {
+  if (typeof ctx?.on === 'function') {
+    const dispose = ctx.on('session/event', listener);
+    return typeof dispose === 'function' ? dispose : () => {};
+  }
+  const events = ctx?.events;
+  if (events !== undefined && typeof events.on === 'function') {
+    const dispose = events.on('session/event', listener);
+    return typeof dispose === 'function' ? dispose : () => {};
+  }
+  return () => {};
+}
+
+/**
+ * The text an event carries, in whatever shape the Host used.
+ *
+ * Kept deliberately tolerant: an event's payload moved between DSH releases
+ * (`data`, `message`, `content`, blocks of `{type:'text'}`). Reading all of them
+ * means one helper survives an upgrade, where pinning one shape would silently
+ * return empty strings.
+ */
+function textOfEvent(event) {
+  const candidates = [event?.text, event?.data?.text, event?.message?.text, event?.data?.message?.text];
+  for (const candidate of candidates) {
+    if (typeof candidate === 'string' && candidate.trim() !== '') return candidate;
+  }
+  for (const block of contentBlocks(event)) {
+    if (typeof block?.text === 'string' && block.text.trim() !== '') return block.text;
+  }
+  return '';
+}
+
+/** Every plausible content-block array in an event. */
+function contentBlocks(event) {
+  const candidates = [event?.content, event?.parts, event?.data?.content, event?.message?.content, event?.data?.message?.content];
+  for (const candidate of candidates) {
+    if (Array.isArray(candidate)) return candidate;
+  }
+  return [];
+}
+
+/** One line about an error, without a stack. */
+function describe(error) {
+  return error instanceof Error ? error.message : String(error);
+}