newsletter-orchestrator

/**
 * Newsletter Orchestrator - Production Reference Agent
 *
 * Canon alignment: KB 55 (MARA), KB 22 (HumanOS)
 * Demonstrates: ctx.call.agent(), delegation chains, provenance
 *
 * Real use case: Fetch headlines -> summarize -> email (multi-agent flow).
 */

import { handler, withProvenanceContext } from '@human/agent-sdk';
import type { ExecutionContext } from '@human/agent-sdk';
import { WORKFLOW_NEWSLETTER_MANIFEST } from './manifest.js';

export const AGENT_ID = 'newsletter-orchestrator';
export const VERSION = '1.0.0';
export const CAPABILITIES = ['content/newsletter/orchestrate'];

export interface NewsletterOrchestratorInput {
  topic: string;
  max_items?: number;
}

export interface NewsletterOrchestratorOutput {
  success: boolean;
  newsletter_path: string;
  headline_count: number;
  provenance_id: string;
  /** Workflow manifest id when running as elevated workflow package */
  workflow_manifest_id?: string;
}

const execute = async (
  ctx: ExecutionContext,
  input: NewsletterOrchestratorInput
): Promise<NewsletterOrchestratorOutput> => {
  ctx.log.info('Orchestrating newsletter', { topic: input.topic });

  // Step 1: Call headline fetcher agent (ctx.call.agent - capability-based routing)
  let headlines: string[];
  try {
    const headlineResult = await ctx.call.agent<{ headlines: string[] }>(
      'content/headlines/fetch',
      { topic: input.topic, limit: input.max_items ?? 5 }
    );
    headlines = headlineResult.data.headlines;
    ctx.log.info('Fetched headlines', { count: headlines.length });
  } catch (err) {
    // Log the failure with context, then degrade gracefully
    ctx.log.warn('Headline fetch failed, using fallback', {
      error: err instanceof Error ? err.message : String(err),
      topic: input.topic,
    });
    headlines = [`Latest developments in ${input.topic}`];
  }

  // Step 2: Call summarizer agent (delegation chain - orchestrator -> summarizer)
  let summary: string;
  try {
    const summaryResult = await ctx.call.agent<{ summary: string }>(
      'content/summarize',
      { items: headlines }
    );
    summary = summaryResult.data.summary;
  } catch (err) {
    ctx.log.warn('Summarizer failed, using raw headlines', {
      error: err instanceof Error ? err.message : String(err),
    });
    summary = headlines.map((h, i) => `${i + 1}. ${h}`).join('\n');
  }

  // Step 3: Write newsletter file
  const newsletterPath = `newsletters/${input.topic}-${new Date().toISOString().slice(0, 10)}.md`;
  await ctx.files.writeText(
    newsletterPath,
    `# Newsletter: ${input.topic}\n\n${summary}\n\n---\nGenerated by HUMΛN Newsletter Orchestrator`
  );

  const provenanceId = await ctx.provenance.log(
    withProvenanceContext(ctx, {
      type: 'newsletter:generated',
      status: 'success',
      metadata: {
        input: { topic: input.topic },
        output: { newsletter_path: newsletterPath, headline_count: headlines.length },
      },
    })
  );

  return {
    workflow_manifest_id: WORKFLOW_NEWSLETTER_MANIFEST.id,
    success: true,
    newsletter_path: newsletterPath,
    headline_count: headlines.length,
    provenance_id: provenanceId,
  };
};

export default handler({
  name: AGENT_ID,
  id: AGENT_ID,
  version: VERSION,
  capabilities: CAPABILITIES,
  manifest: {
    operations: [
      {
        name: 'orchestrate',
        description: 'Fetch headlines, summarize, and produce newsletter for a topic',
        paramsSchema: {
          topic: { type: 'string', required: true, description: 'Newsletter topic' },
          max_items: { type: 'number', description: 'Max headline items' },
        },
        resultKind: 'agent.newsletter-orchestrator.result',
      },
    ],
  },
  execute,
});