AlexandrAI AGENTS.md
agents-md

Personal Work Agent Outbound Processor Agent Guide

Project-specific AGENTS.md guidance for Personal Work Agent outbound queue processing, connector send protocols, token resolution, manual-required outcomes, artifacts, and tests.

AGENTS.md

Guidance for coding agents working on Personal Work Agent outbound processing.

Project Overview

The outbound processor sends approved local outputs to platform connectors, resolves connector tokens, produces sent/failed/manual-required outcomes, writes connector-specific artifacts, and updates case state. It is distinct from review push and from platform ingestion.

Use this boundary when changing outbound queue semantics, connector senders, token resolution, artifact creation, or manual-required handling.

Project Map

  • src/workagent/services/outbound.py defines OutboundQueueProcessor and connector sender/token resolver protocols.
  • src/workagent/connectors/slack_send.py implements Slack outbound sending behavior.
  • src/workagent/services/credentials.py resolves enabled connector tokens.
  • src/workagent/db/enums.py defines connector and case status values used by outbound work.
  • src/workagent/db/models.py contains Case, CaseEvent, AgentWriteDraft, and related output state.
  • src/workagent/app/routes.py exposes internal outbound/process.
  • tests/test_outbound_processor.py, test_slack_send.py, test_app_routes.py, and platform write connector tests cover behavior.

Setup Commands

bashuv run pytest tests/test_outbound_processor.py tests/test_slack_send.py -q
uv run pytest tests/test_app_routes.py tests/test_nk304_write_connectors.py -q
make lint

Change Rules For Agents

  • Keep outbound processing separate from ingestion and review push.
  • Resolve tokens through credential services; do not pass raw token values through case payloads.
  • Preserve manual_required outcomes for unsupported or unsafe sends.
  • Record artifacts and case events for send attempts and outcomes.
  • Keep connector-specific artifact typing in one helper path.
  • Do not retry indefinitely without bounded failure state.
  • Avoid logging platform message bodies when they may contain sensitive content.

Verification

bashuv run pytest tests/test_outbound_processor.py tests/test_slack_send.py tests/test_app_routes.py -q
make lint

Add sender protocol tests when introducing a new outbound platform.

Security Notes

Outbound sends can disclose user content to external systems. Keep approval gates, token redaction, manual-required fallbacks, and artifact trails intact.

PR Checklist

  • Sent, failed, and manual-required outcomes are tested.
  • Token resolution stays credential-service-owned.
  • Artifacts and case events are recorded consistently.
  • New connector senders have protocol tests.