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