dsh-a2a-groups 0.0.0-stage → 0.1.2

package/lib/core/skills-session.js

@@ -0,0 +1,116 @@
+/**
+ * The built-in skills: `ping` and `session/ask`.
+ *
+ * Both exist to answer one question through the whole stack — "did this message
+ * actually reach a Session, and did the Session really work on it?" A `ping`
+ * that only echoes proves the transport; `session/ask` proves the last mile,
+ * because it has to wait for a real turn to end and read what the model said.
+ *
+ * The session skill deliberately does **not** stream. A DSH turn is not a
+ * sequence of protocol-level progress events; pretending its intermediate steps
+ * were A2A `statusUpdate`s would put a made-up progress narrative on the wire.
+ * It reports `submitted` → `working` → a final artifact, which is the truth.
+ *
+ * @module dsh-a2a/skills/session
+ */
+
+/** How long one ask waits for its turn to finish, when the caller names nothing. */
+const DEFAULT_ASK_TIMEOUT_MS = 600000;
+
+/**
+ * `ping` — a transport check.
+ *
+ * Returns the bound Session id and the plugin version so a caller can tell
+ * "the gateway reached a DSH instance" from "the gateway reached *the right*
+ * DSH instance", which is the failure mode that costs an hour when several
+ * machines are behind one gateway.
+ *
+ * @param {object} deps - `{ version, sessionIdOf }`.
+ * @returns {object} the skill definition.
+ */
+export function createPingSkill({ version, sessionIdOf }) {
+  return {
+    id: 'ping',
+    name: 'Ping',
+    description: 'Report the DSH instance behind this agent: its bound Session id and plugin version. Use it to verify connectivity before a real call.',
+    examples: ['ping'],
+    async run() {
+      return {
+        text: JSON.stringify({ pong: true, version, sessionId: sessionIdOf() ?? null }, null, 2),
+      };
+    },
+  };
+}
+
+/**
+ * `session/ask` — put a task into the bound Session and wait for the answer.
+ *
+ * This is the skill that makes a DSH instance an A2A agent: the caller's
+ * message becomes a real turn (the left-hand "task message received" card, not a
+ * bubble that looks like the user typed it), and the Session's last assistant
+ * message becomes the artifact.
+ *
+ * @param {object} deps - `{ deliverer, sessions, logger, config }`.
+ * @returns {object} the skill definition.
+ */
+export function createSessionAskSkill({ deliverer, sessions, logger, config }) {
+  return {
+    id: 'session/ask',
+    name: 'Ask this Session',
+    description:
+      'Deliver a message into this DSH instance\'s bound Session as a task message, wait for the turn to finish, and return what the Session answered.',
+    examples: ['Refactor the invoice module and report what changed', 'Summarise today\'s incident and list the open questions'],
+    async run(input, context) {
+      const text = typeof input.text === 'string' ? input.text.trim() : '';
+      if (text === '') {
+        // A caller that sends no words has nothing to deliver; answering with an
+        // error is better than waking a Session to ask it what it was told.
+        const error = new Error('session/ask needs a non-empty message text');
+        error.code = 'empty_message';
+        throw error;
+      }
+      const sessionId = input.sessionId ?? sessions.resolveBoundSessionId();
+      if (typeof sessionId !== 'string' || sessionId === '') {
+        const error = new Error(
+          'session/ask has no target Session: set server.bindSessionId, or call from a Session once so it can bind itself',
+        );
+        error.code = 'no_bound_session';
+        throw error;
+      }
+      const timeoutMs = clampTimeout(input.timeoutMs, config.server.taskTimeoutMs);
+      const messageId = input.messageId ?? context.messageId;
+
+      // The turn is observed from the Session's own event stream rather than
+      // polled: an answer can arrive in 200ms or in ten minutes, and a poll
+      // interval is either wasteful or slow at exactly the wrong moment.
+      const watcher = sessions.watchTurn(sessionId, { timeoutMs, signal: context.signal });
+      const receipt = await deliverer.deliver({
+        sessionId,
+        text,
+        messageId,
+        mode: 'queue',
+        source: { kind: 'a2a', skill: 'session/ask', taskId: context.taskId, from: input.from },
+      });
+      const outcome = await watcher.done;
+      if (outcome.timedOut) {
+        const error = new Error(`session/ask timed out after ${timeoutMs}ms waiting for the Session to finish`);
+        error.code = 'turn_timeout';
+        throw error;
+      }
+      if (receipt.injected === 'duplicate') {
+        logger?.info?.(`a2a: session/ask message ${messageId} was already delivered; answered from the Session's state`);
+      }
+      return {
+        text: outcome.text === '' ? '(the Session finished its turn without a text answer)' : outcome.text,
+        meta: { sessionId, injected: receipt.injected, timedOut: false },
+      };
+    },
+  };
+}
+
+/** Keep a caller-supplied timeout inside what this server is willing to hold. */
+function clampTimeout(value, ceiling) {
+  const number = typeof value === 'number' ? value : Number(value);
+  if (!Number.isFinite(number) || number <= 0) return Math.min(DEFAULT_ASK_TIMEOUT_MS, ceiling);
+  return Math.max(1000, Math.min(Math.trunc(number), ceiling));
+}

package/lib/core/skills.js

@@ -0,0 +1,76 @@
+/**
+ * The skill registry the A2A server dispatches through.
+ *
+ * A skill is the A2A protocol's unit of capability: it is what the agent card
+ * advertises, what a caller names in `message.metadata.skill`, and what the
+ * server turns into work. Keeping registration separate from both the server
+ * (which knows HTTP and JSON-RPC) and the implementations (which know groups and
+ * sessions) means the server can be tested with fake skills and a skill can be
+ * tested without a socket.
+ *
+ * @module dsh-a2a/skills
+ */
+
+/**
+ * Build the registry.
+ *
+ * Registration is by id and duplicate ids throw: two skills claiming one id
+ * would make a caller's `skill` field ambiguous and the card advertise a
+ * capability that dispatches somewhere unpredictable.
+ *
+ * @returns {{
+ *   register: (skill: object) => (() => boolean),
+ *   get: (id: string) => any,
+ *   list: () => any[],
+ *   ids: () => string[],
+ * }} the registry. The concrete signatures matter: a bare `Function` is not
+ * assignable to a declared call signature, so callers that pass the registry
+ * into `createServer()` would each report an error at their own call site.
+ */
+export function createSkillRegistry() {
+  /** @type {Map<string, object>} */
+  const skills = new Map();
+
+  const register = (skill) => {
+    if (!isPlainObject(skill)) throw new Error('a2a: a skill must be an object');
+    const id = skill.id;
+    if (typeof id !== 'string' || id === '') throw new Error('a2a: a skill needs a non-empty id');
+    if (typeof skill.run !== 'function') throw new Error(`a2a: skill "${id}" needs a run function`);
+    if (skills.has(id)) throw new Error(`a2a: skill "${id}" is registered twice`);
+    skills.set(id, {
+      id,
+      name: typeof skill.name === 'string' && skill.name !== '' ? skill.name : id,
+      description: typeof skill.description === 'string' ? skill.description : '',
+      examples: Array.isArray(skill.examples) ? skill.examples.filter((item) => typeof item === 'string') : [],
+      streaming: skill.streaming === true,
+      run: skill.run,
+    });
+    return () => skills.delete(id);
+  };
+
+  const get = (id) => skills.get(id);
+
+  /**
+   * The card's `skills[]`, i.e. what a caller may name.
+   *
+   * Only metadata leaves this function — never `run` — because the card is
+   * serialized into an HTTP response and a function there would either be
+   * dropped silently or, worse, stringified into the wire.
+   */
+  const list = () => [...skills.values()].map((skill) => ({
+    id: skill.id,
+    name: skill.name,
+    description: skill.description,
+    tags: skill.streaming ? ['streaming'] : [],
+    examples: skill.examples,
+  }));
+
+  const ids = () => [...skills.keys()];
+
+  return { register, get, list, ids };
+}
+
+/** 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);
+}