Function handleGetSignals

server/src/training-agent/task-handlers.ts:2601–2776

(args: ToolArgs, ctx: TrainingContext)

const MAX_SIGNAL_RESULTS = 10;

export async function handleGetSignals(args: ToolArgs, ctx: TrainingContext) {
  const req = args as unknown as GetSignalsRequest & ToolArgs & {
    brief?: string;
    pagination?: { max_results?: number; cursor?: string };
  };
  // Accept both signal_spec (protocol) and brief (SDK test tool)
  const rawSpec = req.signal_spec || req.brief;
  const signalSpec = typeof rawSpec === 'string' ? rawSpec : undefined;
  // Pagination shape (pagination.max_results, schema cap 100) takes precedence
  // over the legacy top-level `max_results` (no schema cap; this handler
  // historically capped at 50 to keep semantic-search results focused). The two
  // forms have different caps because they have different contracts —
  // pagination.max_results is the standard envelope and matches the schema's
  // documented 100 cap; top-level max_results is the predecessor and we
  // preserve its tighter behavioral cap to avoid silently widening any caller
  // currently relying on the 50 ceiling. Spec ambiguity on which form wins
  // when both are present is tracked at adcontextprotocol/adcp#3113.
  let maxResults: number;
  const paginationMax = req.pagination?.max_results;
  if (typeof paginationMax === 'number' && paginationMax >= 1) {
    maxResults = Math.min(paginationMax, 100);
  } else if (typeof req.max_results === 'number' && req.max_results >= 1) {
    maxResults = Math.min(req.max_results, 50);
  } else {
    maxResults = MAX_SIGNAL_RESULTS;
  }
  const offset = decodeOffsetCursor('signals', req.pagination?.cursor);
  if (offset === null) {
    return {
      errors: [{ code: 'INVALID_REQUEST', message: 'pagination.cursor is malformed' }] as TaskError[],
    };
  }
  const session = await getSession(sessionKeyFromArgs(req, ctx.mode, ctx.userId, ctx.moduleId));

  const allSignals = getAllSignals();
  let results = allSignals;

  // Exact lookup by signal_ids
  if (req.signal_ids?.length) {
    const idSet = new Set(req.signal_ids.map(sid => sid.id));
    results = results.filter(s => idSet.has(s.signalAgentSegmentId));
  }

  // Natural language search via signal_spec
  const rawTerms = signalSpec ? signalSpec.toLowerCase().split(/\s+/) : [];
  if (signalSpec) {
    const expanded = new Set<string>();
    for (const t of rawTerms) {
      expanded.add(t);
      const synonyms = SYNONYM_MAP[t];
      if (synonyms) {
        for (const s of synonyms) expanded.add(s);
      }
    }
    const terms = [...expanded];
    const scored = results
      .map(s => {
        const text = `${s.name} ${s.description} ${s.tags.join(' ')} ${s.providerName}`.toLowerCase();