@frontmcp/skills 1.0.0-beta.9 → 1.0.0

package/catalog/frontmcp-development/examples/create-agent/custom-multi-pass-agent.md

@@ -0,0 +1,95 @@
+---
+name: custom-multi-pass-agent
+reference: create-agent
+level: intermediate
+description: 'An agent that overrides `execute()` to perform multi-pass LLM reasoning with `this.completion()`.'
+tags: [development, security, agent, custom, multi, pass]
+features:
+  - 'Overriding `execute()` for custom multi-pass orchestration instead of the default agent loop'
+  - 'Using `this.completion()` to make individual LLM calls with full control over prompts'
+  - 'Using `this.mark(stage)` to track execution stages (security-pass, quality-pass, synthesis)'
+  - 'Defining `outputSchema` with Zod to validate and type-check the structured return value'
+---
+
+# Custom Multi-Pass Agent with Structured Output
+
+An agent that overrides `execute()` to perform multi-pass LLM reasoning with `this.completion()`.
+
+## Code
+
+```typescript
+// src/apps/review/agents/structured-reviewer.agent.ts
+import { Agent, AgentContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Agent({
+  name: 'structured_reviewer',
+  description: 'Reviews code with a structured multi-pass approach',
+  llm: {
+    provider: 'anthropic',
+    model: 'claude-sonnet-4-20250514',
+    apiKey: { env: 'ANTHROPIC_API_KEY' },
+  },
+  inputSchema: {
+    code: z.string().describe('Source code to review'),
+  },
+  outputSchema: {
+    issues: z.array(
+      z.object({
+        severity: z.enum(['error', 'warning', 'info']),
+        line: z.number(),
+        message: z.string(),
+      }),
+    ),
+    summary: z.string(),
+  },
+})
+class StructuredReviewerAgent extends AgentContext {
+  async execute(input: { code: string }) {
+    this.mark('security-pass');
+    const securityReview = await this.completion({
+      messages: [{ role: 'user', content: `Review this code for security issues:\n${input.code}` }],
+    });
+
+    this.mark('quality-pass');
+    const qualityReview = await this.completion({
+      messages: [{ role: 'user', content: `Review this code for quality issues:\n${input.code}` }],
+    });
+
+    this.mark('synthesis');
+    const finalReview = await this.completion({
+      messages: [
+        {
+          role: 'user',
+          content: `Combine these reviews into a structured JSON report with "issues" (array of {severity, line, message}) and "summary" (string):\nSecurity: ${securityReview.content}\nQuality: ${qualityReview.content}`,
+        },
+      ],
+    });
+
+    return JSON.parse(finalReview.content);
+  }
+}
+```
+
+```typescript
+// src/apps/review/index.ts
+import { App } from '@frontmcp/sdk';
+
+@App({
+  name: 'review-app',
+  agents: [StructuredReviewerAgent],
+})
+class ReviewApp {}
+```
+
+## What This Demonstrates
+
+- Overriding `execute()` for custom multi-pass orchestration instead of the default agent loop
+- Using `this.completion()` to make individual LLM calls with full control over prompts
+- Using `this.mark(stage)` to track execution stages (security-pass, quality-pass, synthesis)
+- Defining `outputSchema` with Zod to validate and type-check the structured return value
+
+## Related
+
+- See `create-agent` for streaming with `streamCompletion()`, sub-agents, and swarm handoff
+- See `create-agent-llm-config` for provider-specific options like `maxTokens` and `temperature`

package/catalog/frontmcp-development/examples/create-agent/nested-agents-with-swarm.md

@@ -0,0 +1,111 @@
+---
+name: nested-agents-with-swarm
+reference: create-agent
+level: advanced
+description: 'Composing specialized sub-agents and configuring swarm-based handoff between agents.'
+tags: [development, agent, nested, agents, swarm]
+features:
+  - "Configuring `swarm` with `role: 'coordinator'` for the triage agent and `role: 'specialist'` for domain agents"
+  - 'Defining `handoff` rules with `agent` name and `condition` for declarative LLM-driven routing'
+  - 'Specialist agents can hand back to the triage agent when a request falls outside their scope'
+  - 'Each agent has its own `llm` config, `tools`, and `systemInstructions` for specialization'
+---
+
+# Nested Sub-Agents and Swarm Handoff
+
+Composing specialized sub-agents and configuring swarm-based handoff between agents.
+
+## Code
+
+```typescript
+// src/apps/support/agents/billing.agent.ts
+import { Agent, AgentContext, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'lookup_invoice',
+  description: 'Look up an invoice by ID',
+  inputSchema: { invoiceId: z.string() },
+})
+class LookupInvoiceTool extends ToolContext {
+  async execute(input: { invoiceId: string }) {
+    return { id: input.invoiceId, amount: 99.99, status: 'paid' };
+  }
+}
+
+@Agent({
+  name: 'billing_agent',
+  description: 'Handles billing and payment inquiries',
+  llm: { provider: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
+  tools: [LookupInvoiceTool],
+  swarm: {
+    role: 'specialist',
+    handoff: [{ agent: 'triage_agent', condition: 'Request is outside billing scope' }],
+  },
+})
+class BillingAgent extends AgentContext {}
+```
+
+```typescript
+// src/apps/support/agents/technical.agent.ts
+import { Agent, AgentContext } from '@frontmcp/sdk';
+
+@Agent({
+  name: 'technical_agent',
+  description: 'Handles technical support issues',
+  llm: { provider: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
+  systemInstructions: 'You are a technical support specialist. Diagnose issues and provide solutions.',
+  swarm: {
+    role: 'specialist',
+    handoff: [{ agent: 'triage_agent', condition: 'Request is outside technical scope' }],
+  },
+})
+class TechnicalAgent extends AgentContext {}
+```
+
+```typescript
+// src/apps/support/agents/triage.agent.ts
+import { Agent, AgentContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Agent({
+  name: 'triage_agent',
+  description: 'Triages incoming requests and hands off to specialists',
+  llm: { provider: 'anthropic', model: 'claude-sonnet-4-20250514', apiKey: { env: 'ANTHROPIC_API_KEY' } },
+  inputSchema: {
+    request: z.string().describe('The incoming user request'),
+  },
+  swarm: {
+    role: 'coordinator',
+    handoff: [
+      { agent: 'billing_agent', condition: 'Request is about billing or payments' },
+      { agent: 'technical_agent', condition: 'Request is about technical issues' },
+    ],
+  },
+  systemInstructions: 'Analyze the request and hand off to the appropriate specialist agent.',
+})
+class TriageAgent extends AgentContext {}
+```
+
+```typescript
+// src/apps/support/index.ts
+import { App } from '@frontmcp/sdk';
+
+@App({
+  name: 'support-app',
+  agents: [TriageAgent, BillingAgent, TechnicalAgent],
+})
+class SupportApp {}
+```
+
+## What This Demonstrates
+
+- Configuring `swarm` with `role: 'coordinator'` for the triage agent and `role: 'specialist'` for domain agents
+- Defining `handoff` rules with `agent` name and `condition` for declarative LLM-driven routing
+- Specialist agents can hand back to the triage agent when a request falls outside their scope
+- Each agent has its own `llm` config, `tools`, and `systemInstructions` for specialization
+
+## Related
+
+- See `create-agent` for exported tools, function-style builder, providers, and rate limiting
+- See `create-agent-llm-config` for using different LLM providers per agent

package/catalog/frontmcp-development/examples/create-agent-llm-config/anthropic-config.md

@@ -0,0 +1,81 @@
+---
+name: anthropic-config
+reference: create-agent-llm-config
+level: basic
+description: 'Configuring an agent with the Anthropic provider and common model options.'
+tags: [development, anthropic, llm, agent, config]
+features:
+  - "Setting `provider: 'anthropic'` with a supported model (`claude-sonnet-4-20250514` or `claude-opus-4-20250514`)"
+  - "Using `{ env: 'ANTHROPIC_API_KEY' }` to read the API key from an environment variable"
+  - 'Setting `maxTokens` at the LLM config level and overriding per-call via `this.completion()` options'
+  - 'Passing `temperature` as a per-call option for controlling response creativity'
+---
+
+# Anthropic LLM Configuration
+
+Configuring an agent with the Anthropic provider and common model options.
+
+## Code
+
+```typescript
+// src/apps/main/agents/summarizer.agent.ts
+import { Agent, AgentContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Agent({
+  name: 'summarizer',
+  description: 'Summarizes text using Anthropic Claude',
+  llm: {
+    provider: 'anthropic',
+    model: 'claude-sonnet-4-20250514',
+    apiKey: { env: 'ANTHROPIC_API_KEY' },
+    maxTokens: 4096,
+  },
+  inputSchema: {
+    text: z.string().describe('Text to summarize'),
+  },
+})
+class SummarizerAgent extends AgentContext {
+  async execute(input: { text: string }) {
+    const result = await this.completion(
+      {
+        messages: [{ role: 'user', content: `Summarize this text:\n${input.text}` }],
+      },
+      {
+        maxTokens: 500,
+        temperature: 0.3,
+      },
+    );
+
+    return result.content;
+  }
+}
+```
+
+```typescript
+// For the most capable model:
+@Agent({
+  name: 'complex_reasoner',
+  description: 'Handles complex reasoning tasks',
+  llm: {
+    provider: 'anthropic',
+    model: 'claude-opus-4-20250514',
+    apiKey: { env: 'ANTHROPIC_API_KEY' },
+    maxTokens: 4096,
+  },
+  // ...
+})
+class ComplexReasonerAgent extends AgentContext {}
+```
+
+## What This Demonstrates
+
+- Setting `provider: 'anthropic'` with a supported model (`claude-sonnet-4-20250514` or `claude-opus-4-20250514`)
+- Using `{ env: 'ANTHROPIC_API_KEY' }` to read the API key from an environment variable
+- Setting `maxTokens` at the LLM config level and overriding per-call via `this.completion()` options
+- Passing `temperature` as a per-call option for controlling response creativity
+
+## Related
+
+- See `create-agent-llm-config` for all supported providers and the common models table
+- See `create-agent` for full agent patterns including inner tools and swarm configuration

package/catalog/frontmcp-development/examples/create-agent-llm-config/openai-config.md

@@ -0,0 +1,80 @@
+---
+name: openai-config
+reference: create-agent-llm-config
+level: basic
+description: 'Configuring an agent with the OpenAI provider and different model options.'
+tags: [development, openai, llm, agent, config]
+features:
+  - "Setting `provider: 'openai'` with `gpt-4o` for general purpose or `gpt-4o-mini` for cost-effective tasks"
+  - "The API key pattern `{ env: 'OPENAI_API_KEY' }` works the same across all providers"
+  - 'Combining LLM config with inner tools -- the agent uses OpenAI to reason about tool invocations'
+  - 'Choosing the right model for the task: `gpt-4o` for complex workflows, `gpt-4o-mini` for fast classification'
+---
+
+# OpenAI LLM Configuration
+
+Configuring an agent with the OpenAI provider and different model options.
+
+## Code
+
+```typescript
+// src/apps/main/agents/data-pipeline.agent.ts
+import { Agent, AgentContext, Tool, ToolContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'extract_data',
+  description: 'Extract data from a source',
+  inputSchema: { source: z.string() },
+})
+class ExtractTool extends ToolContext {
+  async execute(input: { source: string }) {
+    return { data: `extracted from ${input.source}` };
+  }
+}
+
+@Agent({
+  name: 'data_pipeline',
+  description: 'Data processing pipeline agent',
+  llm: {
+    provider: 'openai',
+    model: 'gpt-4o',
+    apiKey: { env: 'OPENAI_API_KEY' },
+    maxTokens: 4096,
+  },
+  inputSchema: {
+    source: z.string().describe('Data source to process'),
+  },
+  tools: [ExtractTool],
+  systemInstructions: 'You are a data processing agent. Extract and transform data from the given source.',
+})
+class DataPipelineAgent extends AgentContext {}
+```
+
+```typescript
+// For a cost-effective model:
+@Agent({
+  name: 'quick_classifier',
+  description: 'Fast classification of incoming requests',
+  llm: {
+    provider: 'openai',
+    model: 'gpt-4o-mini',
+    apiKey: { env: 'OPENAI_API_KEY' },
+    maxTokens: 1024,
+  },
+  // ...
+})
+class QuickClassifierAgent extends AgentContext {}
+```
+
+## What This Demonstrates
+
+- Setting `provider: 'openai'` with `gpt-4o` for general purpose or `gpt-4o-mini` for cost-effective tasks
+- The API key pattern `{ env: 'OPENAI_API_KEY' }` works the same across all providers
+- Combining LLM config with inner tools -- the agent uses OpenAI to reason about tool invocations
+- Choosing the right model for the task: `gpt-4o` for complex workflows, `gpt-4o-mini` for fast classification
+
+## Related
+
+- See `create-agent-llm-config` for the complete common models table and API key source options
+- See `create-agent` for sub-agents using different providers for specialized tasks

package/catalog/frontmcp-development/examples/create-job/basic-report-job.md

@@ -0,0 +1,87 @@
+---
+name: basic-report-job
+reference: create-job
+level: basic
+description: 'A minimal job that generates a report with progress tracking and structured output.'
+tags: [development, job, report]
+features:
+  - 'Defining a job with `@Job` decorator including `inputSchema`, `outputSchema`, and `timeout`'
+  - 'Reporting progress at each stage using `this.progress(pct, total, message)`'
+  - 'Using `this.log()` for persistent, queryable log entries'
+---
+
+# Basic Report Generation Job
+
+A minimal job that generates a report with progress tracking and structured output.
+
+## Code
+
+```typescript
+// src/jobs/generate-report.job.ts
+import { Job, JobContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Job({
+  name: 'generate-report',
+  description: 'Generate a PDF report from data',
+  inputSchema: {
+    reportType: z.enum(['sales', 'inventory', 'users']).describe('Type of report'),
+    dateRange: z.object({
+      from: z.string().describe('Start date (ISO 8601)'),
+      to: z.string().describe('End date (ISO 8601)'),
+    }),
+    format: z.enum(['pdf', 'csv']).default('pdf').describe('Output format'),
+  },
+  outputSchema: {
+    url: z.string().url(),
+    pageCount: z.number().int(),
+    generatedAt: z.string(),
+  },
+  timeout: 120000,
+})
+class GenerateReportJob extends JobContext {
+  async execute(input: {
+    reportType: 'sales' | 'inventory' | 'users';
+    dateRange: { from: string; to: string };
+    format: 'pdf' | 'csv';
+  }) {
+    this.log(`Starting ${input.reportType} report generation`);
+
+    this.progress(10, 100, 'Fetching data');
+    const data = await this.fetchReportData(input.reportType, input.dateRange);
+
+    this.progress(50, 100, 'Generating document');
+    const document = await this.buildDocument(data, input.format);
+
+    this.progress(90, 100, 'Uploading');
+    const url = await this.uploadDocument(document);
+
+    this.progress(100, 100, 'Complete');
+    return {
+      url,
+      pageCount: document.pages,
+      generatedAt: new Date().toISOString(),
+    };
+  }
+
+  private async fetchReportData(type: string, range: { from: string; to: string }) {
+    return { rows: [], count: 0 };
+  }
+  private async buildDocument(data: unknown, format: string) {
+    return { pages: 5, buffer: Buffer.alloc(0) };
+  }
+  private async uploadDocument(doc: { buffer: Buffer }) {
+    return 'https://storage.example.com/reports/report-001.pdf';
+  }
+}
+```
+
+## What This Demonstrates
+
+- Defining a job with `@Job` decorator including `inputSchema`, `outputSchema`, and `timeout`
+- Reporting progress at each stage using `this.progress(pct, total, message)`
+- Using `this.log()` for persistent, queryable log entries
+
+## Related
+
+- See `create-job` for the full API reference including retry policies and permissions

package/catalog/frontmcp-development/examples/create-job/job-with-permissions.md

@@ -0,0 +1,117 @@
+---
+name: job-with-permissions
+reference: create-job
+level: advanced
+description: 'A data export job with declarative permission controls, plus a function-style job for simple tasks.'
+tags: [development, redis, job, permissions]
+features:
+  - 'Declarative `permissions` with `actions`, `roles`, `scopes`, and a custom `predicate`'
+  - 'Using `tags` and `labels` for categorization and filtering'
+  - 'The `job()` function builder for simple jobs that need no class'
+  - 'Full server registration with `jobs.enabled: true` and a Redis store'
+---
+
+# Job with Permissions, Tags, and Function Builder
+
+A data export job with declarative permission controls, plus a function-style job for simple tasks.
+
+## Code
+
+```typescript
+// src/jobs/data-export.job.ts
+import { Job, JobContext, job } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Job({
+  name: 'data-export',
+  description: 'Export data to external storage',
+  inputSchema: {
+    dataset: z.string(),
+    destination: z.string().url(),
+  },
+  outputSchema: {
+    exportedRows: z.number().int(),
+    location: z.string().url(),
+  },
+  tags: ['export', 'data'],
+  labels: { team: 'data-engineering', priority: 'high' },
+  permissions: {
+    actions: ['create', 'read', 'execute', 'list'],
+    roles: ['admin', 'data-engineer'],
+    scopes: ['jobs:write', 'data:export'],
+    predicate: (ctx) => ctx.user?.department === 'engineering',
+  },
+})
+class DataExportJob extends JobContext {
+  async execute(input: { dataset: string; destination: string }) {
+    this.log(`Exporting dataset: ${input.dataset}`);
+    const rows = await this.exportData(input.dataset, input.destination);
+    return { exportedRows: rows, location: input.destination };
+  }
+
+  private async exportData(dataset: string, destination: string) {
+    return 1000;
+  }
+}
+
+// Function-style job for simple tasks
+const CleanupTempFiles = job({
+  name: 'cleanup-temp-files',
+  description: 'Remove temporary files older than the specified age',
+  inputSchema: {
+    directory: z.string().describe('Directory to clean'),
+    maxAgeDays: z.number().int().min(1).default(7),
+  },
+  outputSchema: {
+    deleted: z.number().int(),
+    freedBytes: z.number().int(),
+  },
+})((input, ctx) => {
+  ctx.log(`Cleaning ${input.directory}, max age: ${input.maxAgeDays} days`);
+  ctx.progress(0, 100, 'Scanning directory');
+
+  // ... scan and delete logic ...
+
+  ctx.progress(100, 100, 'Cleanup complete');
+  return { deleted: 42, freedBytes: 1024000 };
+});
+```
+
+```typescript
+// src/server.ts
+import { FrontMcp, App } from '@frontmcp/sdk';
+
+@App({
+  name: 'data-app',
+  jobs: [DataExportJob, CleanupTempFiles],
+})
+class DataApp {}
+
+@FrontMcp({
+  info: { name: 'data-server', version: '1.0.0' },
+  apps: [DataApp],
+  jobs: {
+    enabled: true,
+    store: {
+      redis: {
+        provider: 'redis',
+        host: 'localhost',
+        port: 6379,
+        keyPrefix: 'mcp:jobs:',
+      },
+    },
+  },
+})
+class DataServer {}
+```
+
+## What This Demonstrates
+
+- Declarative `permissions` with `actions`, `roles`, `scopes`, and a custom `predicate`
+- Using `tags` and `labels` for categorization and filtering
+- The `job()` function builder for simple jobs that need no class
+- Full server registration with `jobs.enabled: true` and a Redis store
+
+## Related
+
+- See `create-job` for the complete permissions reference and all job registration options

package/catalog/frontmcp-development/examples/create-job/job-with-retry.md

@@ -0,0 +1,88 @@
+---
+name: job-with-retry
+reference: create-job
+level: intermediate
+description: 'A job that syncs data from an external API with automatic retry, exponential backoff, and batch progress tracking.'
+tags: [development, job, retry]
+features:
+  - 'Configuring `retry` with `maxAttempts`, `backoffMs`, `backoffMultiplier`, and `maxBackoffMs`'
+  - 'Using `this.attempt` to log retry context (1-based attempt counter)'
+  - 'Using `this.fail()` to abort execution and trigger the retry flow'
+  - 'Combining batch processing with `this.progress()` for granular tracking'
+---
+
+# Job with Retry Policy and Batch Processing
+
+A job that syncs data from an external API with automatic retry, exponential backoff, and batch progress tracking.
+
+## Code
+
+```typescript
+// src/jobs/sync-external-api.job.ts
+import { Job, JobContext } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Job({
+  name: 'sync-external-api',
+  description: 'Synchronize data from an external API',
+  inputSchema: {
+    endpoint: z.string().url().describe('API endpoint to sync from'),
+    batchSize: z.number().int().min(1).max(1000).default(100),
+  },
+  outputSchema: {
+    synced: z.number().int(),
+    errors: z.number().int(),
+  },
+  timeout: 600000, // 10 minutes
+  retry: {
+    maxAttempts: 5,
+    backoffMs: 2000,
+    backoffMultiplier: 2,
+    maxBackoffMs: 60000,
+  },
+})
+class SyncExternalApiJob extends JobContext {
+  async execute(input: { endpoint: string; batchSize: number }) {
+    this.log(`Attempt ${this.attempt}: syncing from ${input.endpoint}`);
+
+    const response = await this.fetch(input.endpoint);
+    if (!response.ok) {
+      this.fail(new Error(`API returned ${response.status}`));
+    }
+
+    const data = await response.json();
+    let synced = 0;
+    let errors = 0;
+
+    for (let i = 0; i < data.items.length; i += input.batchSize) {
+      const batch = data.items.slice(i, i + input.batchSize);
+      this.progress(i, data.items.length, `Processing batch ${Math.floor(i / input.batchSize) + 1}`);
+
+      try {
+        await this.processBatch(batch);
+        synced += batch.length;
+      } catch (err) {
+        errors += batch.length;
+        this.log(`Batch error: ${err}`);
+      }
+    }
+
+    return { synced, errors };
+  }
+
+  private async processBatch(batch: unknown[]) {
+    // process batch
+  }
+}
+```
+
+## What This Demonstrates
+
+- Configuring `retry` with `maxAttempts`, `backoffMs`, `backoffMultiplier`, and `maxBackoffMs`
+- Using `this.attempt` to log retry context (1-based attempt counter)
+- Using `this.fail()` to abort execution and trigger the retry flow
+- Combining batch processing with `this.progress()` for granular tracking
+
+## Related
+
+- See `create-job` for the full retry policy reference and backoff schedule