feat: add composable guardrails for TACTool (rate limiting)

[yatharth-1504]

Summary

Adds a composable guardrail system to packages/tools that lets developers wrap any TACTool with rate limiting before the tool's implementation runs. This is the foundation for a broader guardrail system (content filtering + withGuardrails() wrapper coming in a follow-up PR).

New files:

• packages/tools/src/lib/errors.ts — GuardrailError with a type field ('rate_limit' | 'content_filter')
• packages/tools/src/lib/rate-limiter.ts — SlidingWindowRateLimiter (sliding window, in-memory, per-key)

Modified:

• packages/tools/src/index.ts — exports GuardrailError publicly

Usage preview (once withGuardrails() lands in the follow-up):

import { createSendMessageTool, withGuardrails } from 'twilio-agent-connect';

const safeSendMessage = withGuardrails(
  createSendMessageTool(channel, conversationId),
  {
    rateLimit: {
      maxCalls: 5,
      windowMs: 60_000,
      keyFn: () => conversationId, // per-conversation limit
    },
  }
);

When the limit is exceeded, GuardrailError is thrown — LLM SDKs surface this as a tool-result message so the model can respond gracefully ("I've sent too many messages, please wait a moment").

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update
• Refactoring

Checklist

• Tests added/updated
• Documentation updated
• Tested E2E

SDK Parity

• Change is TypeScript-specific (no Python update needed)

[Copilot]

Pull request overview

Adds an initial “guardrails” foundation to the packages/tools package by introducing a typed GuardrailError and an in-memory sliding-window rate limiter intended to run before a TACTool implementation executes.

Changes:

• Introduces GuardrailError with a discriminating type (rate_limit / content_filter) for guardrail failures.
• Adds SlidingWindowRateLimiter (per-key, in-memory) to enforce call limits within a time window.
• Adds Vitest coverage for the new error type and rate-limiter behavior, and exports GuardrailError from the tools package entrypoint.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/rate-limiter.test.ts	Adds unit tests for sliding-window rate limiting behavior (limits, reset, per-key isolation).
tests/guardrails.test.ts	Adds unit tests for GuardrailError shape (name, message, type).
packages/tools/src/lib/rate-limiter.ts	Introduces SlidingWindowRateLimiter implementation for rate limiting guardrails.
packages/tools/src/lib/errors.ts	Adds GuardrailError used to signal guardrail blocks.
packages/tools/src/index.ts	Exports GuardrailError from the tools package public API.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.