send

Intent

Send a message, event, or payload to an external destination with full policy enforcement, approval gates, and audit trail. This capability handles external side effects that cannot be undone.

CRITICAL: This capability requires explicit user approval before execution.

Success criteria:

• •Message delivered to destination successfully
• •All policy constraints verified before sending
• •Approval gate passed (explicit user confirmation)
• •Complete audit trail of what was sent
• •Delivery confirmation obtained where possible

Compatible schemas:

• •schemas/output_schema.yaml

Inputs

Procedure

1. •

   Verify approval: Confirm explicit user approval exists

   • •Check approval_token is valid and recent
   • •BLOCK send if approval is missing or expired
   • •Log approval verification for audit
2. •

   Verify checkpoint: Confirm recovery point exists

   • •Validate checkpoint_ref references valid checkpoint
   • •BLOCK send if checkpoint is missing
   • •External sends are irreversible - checkpoint is for state recovery
3. •

   Validate destination: Ensure target is permitted

   • •Check destination against allowlist if defined
   • •Verify destination format matches protocol
   • •Block sends to disallowed destinations
4. •

   Apply constraints: Enforce policy limits

   • •Check rate limits have not been exceeded
   • •Verify message size within bounds
   • •Validate message format against schema
   • •Apply constrain capability rules
5. •

   Prepare payload: Format message for transmission

   • •Serialize according to protocol requirements
   • •Add required headers/metadata
   • •Generate message ID for tracking
   • •Record payload summary (not full content if sensitive)
6. •

   Execute send: Transmit to destination

   • •Use appropriate protocol handler
   • •Capture response or confirmation
   • •Handle timeouts gracefully
   • •Retry according to policy if configured
7. •

   Verify delivery: Confirm successful transmission

   • •Check response status/acknowledgment
   • •Log delivery confirmation
   • •Capture any error responses
8. •

   Audit trail: Record complete send operation

   • •What was sent (summary, not sensitive content)
   • •Where it was sent
   • •When it was sent
   • •Delivery status
   • •Approval reference

Output Contract

Return a structured object:

sent:
  destination: string  # Where message was sent
  payload_type: string  # Type of content sent
  payload_summary: string  # Non-sensitive summary of payload
  timestamp: string  # ISO timestamp of send
  message_id: string | null  # Tracking ID if available
delivery:
  status: sent | queued | failed  # Delivery outcome
  confirmation: string | null  # Delivery receipt or acknowledgment
  retry_count: integer  # Number of retry attempts
  response_code: integer | null  # HTTP status or protocol response
  error: string | null  # Error message if failed
constraints_applied:
  - constraint: string  # What constraint was checked
    enforced: boolean  # Whether it passed
    details: string | null  # Additional context
approval:
  token: string  # Approval token used
  timestamp: string  # When approval was given
  scope: string  # What was approved
confidence: 0..1  # Confidence in successful delivery
evidence_anchors: ["log:timestamp", "api:response"]
assumptions: []  # Explicit assumptions

Field Definitions

Examples

Example 1: API Webhook Notification

Input:

destination: "https://api.partner.com/webhooks/order-updates"
message:
  event: "order.completed"
  order_id: "ORD-12345"
  timestamp: "2024-01-15T10:30:00Z"
  customer_notified: true
protocol: "http"
approval_token: "approve-send-2024-01-15-001"
checkpoint_ref: "checkpoint-2024-01-15-001"
constraints:
  rate_limit: "100/hour"
  allowed_domains: ["api.partner.com"]

Output:

sent:
  destination: "https://api.partner.com/webhooks/order-updates"
  payload_type: "order.completed event"
  payload_summary: "Order completion notification for ORD-12345"
  timestamp: "2024-01-15T10:30:15Z"
  message_id: "msg-abc123"
delivery:
  status: sent
  confirmation: "HTTP 200 OK, body: {\"received\": true}"
  retry_count: 0
  response_code: 200
  error: null
constraints_applied:
  - constraint: "rate_limit: 100/hour"
    enforced: true
    details: "Current rate: 45/hour"
  - constraint: "allowed_domains"
    enforced: true
    details: "api.partner.com is in allowlist"
approval:
  token: "approve-send-2024-01-15-001"
  timestamp: "2024-01-15T10:30:00Z"
  scope: "Send order notification to partner API"
confidence: 0.95
evidence_anchors:
  - "log:2024-01-15T10:30:15Z:send-success"
  - "api:response:200-OK"
assumptions:
  - "Partner API is available and processing webhooks"

Evidence pattern: HTTP response code and body confirmation, timestamped log entry.

Example 2: Email Notification (with failure)

Input:

destination: "smtp://mail.company.com:587"
message:
  to: "user@example.com"
  subject: "Action Required: Review pending"
  body: "You have 3 items awaiting review..."
protocol: "smtp"
approval_token: "approve-email-2024-01-15-002"
checkpoint_ref: "checkpoint-2024-01-15-002"
timeout: 30000

Output:

sent:
  destination: "smtp://mail.company.com:587"
  payload_type: "email"
  payload_summary: "Email to user@example.com regarding pending review"
  timestamp: "2024-01-15T11:00:05Z"
  message_id: null
delivery:
  status: failed
  confirmation: null
  retry_count: 3
  response_code: null
  error: "Connection timeout after 30s - SMTP server unreachable"
constraints_applied:
  - constraint: "recipient_validation"
    enforced: true
    details: "Email format valid"
approval:
  token: "approve-email-2024-01-15-002"
  timestamp: "2024-01-15T11:00:00Z"
  scope: "Send review notification email"
confidence: 0.0
evidence_anchors:
  - "log:2024-01-15T11:00:05Z:smtp-timeout"
  - "error:connection-refused"
assumptions:
  - "SMTP server should be available on port 587"
next_actions:
  - "Verify SMTP server status"
  - "Check network connectivity"
  - "Retry with backup mail server if available"

Verification

• • Approval token is valid and not expired
• • Checkpoint reference exists
• • Destination passes policy validation
• • All constraints were checked before send
• • Delivery status is accurately reported
• • Audit trail is complete

Verification tools: Read (for logs), Bash (for health checks)

Safety Constraints

• •mutation: true
• •requires_checkpoint: true
• •requires_approval: true
• •risk: high

Capability-specific rules:

• •NEVER send without explicit user approval (CRITICAL)
• •NEVER send without a valid checkpoint reference
• •ALWAYS validate destination against policy before sending
• •ALWAYS log what was sent for audit (sanitize sensitive data)
• •DO NOT retry indefinitely - respect retry limits
• •BLOCK sends to destinations not in allowlist when list is defined
• •If approval token is missing, REQUEST approval before proceeding
• •Never send credentials, API keys, or secrets in payloads

APPROVAL GATE REQUIREMENT: Before any send operation, the user must explicitly approve:

1. •What will be sent (summary)
2. •Where it will be sent (destination)
3. •Why it is being sent (context)

The approval must be captured with a token that is referenced in this operation.

Composition Patterns

Commonly follows:

• •constrain - Apply policy limits before sending (REQUIRED)
• •checkpoint - Create recovery point before external send (REQUIRED)
• •plan - Sends are typically part of a larger plan
• •transform - Format data before sending

Commonly precedes:

• •audit - Record what was sent for compliance
• •verify - Confirm delivery where possible
• •receive - May expect response from destination

Anti-patterns:

• •NEVER send without constrain check (policy bypass)
• •NEVER send without checkpoint (no state recovery)
• •NEVER send without explicit approval (unauthorized action)
• •NEVER retry failed sends indefinitely (resource exhaustion)

Workflow references:

• •See reference/composition_patterns.md#anti-patterns for send safety rules
• •See reference/composition_patterns.md#digital-twin-sync-loop for send in sync context