dsh-a2a-groups 0.0.0-stage → 0.1.2

package/lib/dsh/toolkit.js

@@ -0,0 +1,166 @@
+/**
+ * A tiny, dependency-free tool toolkit.
+ *
+ * DSH ships `defineTool`, but importing it means a bare `@deepseek-ai/...`
+ * specifier, and a plugin that lives outside the installation (a profile
+ * plugin, a workspace plugin) is loaded by plain Node resolution: its own bare
+ * imports must resolve from the plugin's own directory. This module keeps that
+ * property while still giving the registry the exact `ToolDefinition` shape it
+ * demands.
+ *
+ * Deliberate duplication of `dsh-session-bus/lib/toolkit.js`: depending on
+ * another plugin's internals would break when either is upgraded on its own, and
+ * this file is pure functions. Sharing the shape matters; sharing the file does
+ * not.
+ *
+ * The delivered surface is purposely the same:
+ *   { name, description, parameters, output: { schema, render }, execute }
+ *
+ * @module dsh-a2a/toolkit
+ */
+
+/**
+ * Build one registry-ready tool definition with strict argument validation.
+ * @param {object} options - tool definition.
+ * @param {string} options.name - model-facing tool name.
+ * @param {string} options.description - model-facing description.
+ * @param {object} [options.parameters] - raw JSON Schema for the arguments.
+ * @param {{schema: object, render: (args: object, value: object) => Array<object>}} options.output - result schema and renderer.
+ * @param {(args: object, exec: object) => Promise<object>} options.execute - tool body.
+ * @returns {object} the registry-ready definition.
+ */
+export function defineTool(options) {
+  if (typeof options?.name !== 'string' || options.name === '') throw new Error('tool definition needs a non-empty name');
+  if (typeof options.description !== 'string' || options.description === '') throw new Error(`tool "${options.name}" needs a description`);
+  if (options.output === undefined || typeof options.output.render !== 'function') throw new Error(`tool "${options.name}" must declare output.render`);
+  if (options.output.schema === undefined) throw new Error(`tool "${options.name}" must declare output.schema`);
+  const parameters = options.parameters ?? emptyObjectSchema();
+  return {
+    name: options.name,
+    description: options.description,
+    parameters,
+    output: {
+      schema: options.output.schema,
+      render: (args, value) => options.output.render(args, value),
+    },
+    async execute(args, exec) {
+      const violations = validateArgs(parameters, args);
+      if (violations.length > 0) throw new Error(`invalid arguments: ${violations.join('; ')}`);
+      // Shape the result to the declared contract BEFORE it reaches the registry.
+      // The registry validates results with `additionalProperties: false` and
+      // rejects the whole call on one undeclared field — but by then the tool
+      // body has already run (a Session may have been created, a message
+      // delivered), so a schema drift would surface as "the tool failed" while
+      // the side effect stood. Projecting here makes that class impossible.
+      return projectToSchema(await options.execute(args, exec), options.output.schema);
+    },
+  };
+}
+
+/**
+ * Keep only the fields the declared output schema describes.
+ *
+ * The schema is the contract: a field the schema does not declare is dropped
+ * rather than shipped to a validator that would fail the call. Recurses through
+ * arrays and nested objects, so item shapes are covered too. A `null` or
+ * `undefined` value is treated as absent, which is how optional keys are
+ * omitted rather than sent as `null`.
+ *
+ * @param {unknown} value - the tool body's result.
+ * @param {object} schema - the declared output schema.
+ * @returns {unknown} the projected result.
+ */
+export function projectToSchema(value, schema) {
+  if (value === undefined || value === null) return value;
+  if (schema?.type === 'array' && Array.isArray(value)) {
+    if (schema.items === undefined) return value;
+    return value.map((item) => projectToSchema(item, schema.items));
+  }
+  if (schema?.type === 'object' && isPlainObject(value) && isPlainObject(schema.properties)) {
+    const projected = {};
+    for (const key of Object.keys(schema.properties)) {
+      const item = value[key];
+      if (item === undefined || item === null) continue;
+      projected[key] = projectToSchema(item, schema.properties[key]);
+    }
+    return projected;
+  }
+  return value;
+}
+
+/** A parameterless tool's argument schema. */
+export function emptyObjectSchema() {
+  return { type: 'object', additionalProperties: false, properties: {} };
+}
+
+/**
+ * Validate model-supplied arguments against a raw JSON Schema subset.
+ * @param {object} schema - schema with `type`, `properties`, `required`, `additionalProperties`.
+ * @param {unknown} args - candidate arguments.
+ * @param {string} [root] - diagnostic path prefix for nested calls.
+ * @returns {string[]} path-qualified violations; empty means valid.
+ */
+export function validateArgs(schema, args, root = '') {
+  if (!isPlainObject(args)) return [`${root === '' ? 'arguments' : `"${root.replace(/\.$/, '')}"`} must be a JSON object`];
+  const properties = isPlainObject(schema?.properties) ? schema.properties : {};
+  const required = Array.isArray(schema?.required) ? schema.required : [];
+  const violations = [];
+  for (const key of required) {
+    if (!Object.hasOwn(args, key) || args[key] === undefined) violations.push(`missing required property "${root}${key}"`);
+  }
+  if (schema?.additionalProperties === false) {
+    for (const key of Object.keys(args)) {
+      if (!Object.hasOwn(properties, key)) violations.push(`"${root}${key}" is not a declared property`);
+    }
+  }
+  for (const [key, value] of Object.entries(args)) {
+    const spec = properties[key];
+    if (spec === undefined || value === undefined) continue;
+    violations.push(...checkValue(spec, value, `${root}${key}`));
+  }
+  return violations;
+}
+
+/** Validate one value against one schema node. */
+function checkValue(spec, value, path) {
+  const violations = [];
+  switch (spec.type) {
+    case 'string':
+      if (typeof value !== 'string') return [`"${path}" must be a string`];
+      break;
+    case 'integer':
+      if (typeof value !== 'number' || !Number.isInteger(value)) return [`"${path}" must be an integer`];
+      break;
+    case 'number':
+      if (typeof value !== 'number' || !Number.isFinite(value)) return [`"${path}" must be a finite number`];
+      break;
+    case 'boolean':
+      if (typeof value !== 'boolean') return [`"${path}" must be a boolean`];
+      break;
+    case 'array':
+      if (!Array.isArray(value)) return [`"${path}" must be an array`];
+      if (spec.items !== undefined) {
+        for (let index = 0; index < value.length; index += 1) {
+          violations.push(...checkValue(spec.items, value[index], `${path}[${index}]`));
+        }
+      }
+      return violations;
+    case 'object':
+      // `root` ends with a dot so nested keys keep one uniform path.
+      return validateArgs(spec, value, `${path}.`);
+    default:
+      break;
+  }
+  if (Array.isArray(spec.enum) && !spec.enum.includes(value)) {
+    violations.push(`"${path}" must be one of ${JSON.stringify(spec.enum)}`);
+  }
+  if (Object.hasOwn(spec, 'const') && value !== spec.const) {
+    violations.push(`"${path}" must be ${JSON.stringify(spec.const)}`);
+  }
+  return violations;
+}
+
+/** 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/dsh/tools.js

@@ -0,0 +1,101 @@
+/**
+ * The DSH adapter for the tool surface.
+ *
+ * Three things happen here and nothing else: read the shared specs, hand each one to the
+ * Host's `defineTool`, and route execution through the shared runtime.
+ *
+ * The split exists because a second host is being added. An MCP server needs the same
+ * nineteen tools with the same descriptions and the same results; if this file also held
+ * the logic, that server would either duplicate it or drift from it. Now the two hosts
+ * differ only in how they are called:
+ *
+ *   DSH  ctx.tools.register(spec + execute)   →  execute(args, exec) → runtime.call(name, args, { sessionId: exec.agent.id })
+ *   MCP  tools/list + tools/call              →  runtime.call(name, args, { sessionId })
+ *
+ * @module dsh-a2a/tools
+ */
+
+import { defineTool } from './toolkit.js';
+import { allSpecs } from '../shared/tool-specs.js';
+import { createToolRuntime } from '../shared/tool-runtime.js';
+
+/**
+ * Register every tool on the Host.
+ *
+ * @param {object} ctx - Host context; `ctx.tools.register` is the only capability used.
+ * @param {object} deps - the store, registry, bridge and friends the runtime needs.
+ * @returns {{names: string[], runtime: object}} what was registered, for tests and logs.
+ */
+export function registerTools(ctx, deps) {
+  const runtime = createToolRuntime(deps);
+
+  /** The Session a tool call arrives from. DSH puts it at `exec.agent.id`. */
+  const callerOf = (exec) => ({
+    sessionId: exec?.agent?.id,
+  });
+
+  const registered = [];
+  for (const spec of allSpecs()) {
+    ctx.tools.register(defineTool({
+      name: spec.name,
+      description: spec.description,
+      parameters: spec.parameters,
+      output: spec.output,
+      // One line of glue: hand the call to the shared runtime with the Session identity.
+      // These tool bodies are host-agnostic, so the adapter supplies the one fact only
+      // this host knows.
+      execute: (args, exec) => runtime.call(spec.name, args, callerOf(exec)),
+    }));
+    registered.push(spec.name);
+  }
+
+  return { names: registered, runtime };
+}
+
+export function joinUrl(base, agent) {
+  return `${String(base).replace(/\/+$/, '')}/${String(agent).replace(/^\/+/, '')}`;
+}
+
+export function coded(code, message) {
+  const error = new Error(`[${code}] ${message}`);
+  error.code = code;
+  return error;
+}
+
+export function parseInviteLink(link) {
+  let url;
+  try {
+    url = new URL(link);
+  } catch {
+    throw coded('invalid_link', 'that does not look like an invite link (expected agent-a2a://group?...).');
+  }
+  if (url.protocol !== 'agent-a2a:' || url.hostname !== 'group') {
+    throw coded('invalid_link', 'that is not an agent-a2a group invite link.');
+  }
+  const params = url.searchParams;
+  const groupId = params.get('g') ?? '';
+  if (groupId === '') throw coded('invalid_link', 'the invite link carries no group id.');
+  // The gateway base and agent name are what make the link usable from another
+  // machine; a link without them can only address a group on this instance.
+  const gatewayBase = params.get('gw') ?? '';
+  const agent = params.get('agent') ?? '';
+  const direct = params.get('url') ?? '';
+  const token = params.get('t') ?? '';
+  // `agent` is the HOST's name in the gateway, not the group id. Falling back to
+  // the group id here would send a colleague to an agent that does not exist —
+  // and because a group id looks plausible, the failure reads as "the gateway is
+  // broken" rather than "this link is malformed".
+  const endpoint = direct !== ''
+    ? direct
+    : (gatewayBase === '' || agent === '' ? undefined : joinUrl(gatewayBase, agent));
+  return {
+    groupId,
+    token: token === '' ? undefined : token,
+    gatewayBase: gatewayBase === '' ? undefined : gatewayBase,
+    agent: agent === '' ? undefined : agent,
+    endpoint,
+    baseUrl: endpoint,
+    groupName: params.get('n') ?? undefined,
+    expiresAt: params.get('e') ?? undefined,
+  };
+}