docs: add external task trigger integration example

[ArisLiWind]

Summary

• Add a minimal external-system-driven AgentTeams integration example
• Accept a structured task envelope with external job metadata
• Generate task_id / trace_id for per-submission correlation
• Bridge the task through the existing Manager-centered Matrix task submission path
• Document production considerations: authentication, RBAC, persistence, idempotency, retry, audit

Changes

scripts/external-task-trigger.py (~160 lines)

• Adapter that bridges structured JSON tasks into AgentTeams via the existing Matrix-based Manager submission path
• Reuses scripts/replay-task.sh for Matrix transport — no new Matrix client
• Generates task_id and trace_id for traceability
• Preserves external_job_id from metadata through to output
• Supports --dry-run mode (no Matrix/LLM needed)
• Supports --no-wait mode for fire-and-forget submission
• Zero new dependencies — Python stdlib only
• Returns structured JSON: {task_id, trace_id, status, result, external_job_id, submitted_at}

scripts/example-task.json

• Example structured task with team, skill, params, and metadata

tests/test_external_task_trigger.py (25 tests)

• Task validation (required fields, type checks)
• ID generation (format, uniqueness)
• Manager message building (trace IDs in message body)
• Task loading (file, stdin, error cases)
• Dry-run mode (completes without Matrix)
• Error handling (missing fields, invalid JSON)
• Traceability (external_job_id preserved, timestamps present)

docs/usage/integrations/external-task-trigger.md

• Explains the integration pattern and architecture
• Documents input/output schemas
• Provides usage examples (dry-run and live)
• Clearly states: "This is an integration example, not a production task API"
• Lists production requirements (auth, RBAC, persistence, etc.)

Architecture

External system (CRM, ticket, workflow engine)
        |
        v
  Structured JSON task
  {team, skill, params, metadata}
        |
        v
  Task envelope generator
  (task_id + trace_id)
        |
        v
  Manager message builder
  (deterministic, parseable)
        |
        v
  replay-task.sh (Matrix bridge)
        |
        v
  AgentTeams Manager
  (existing collaboration mechanism)
        |
        v
  Structured result
  {task_id, trace_id, status, result}

Testing

python3 -m pytest tests/test_external_task_trigger.py -v
# 25 passed

python3 -m py_compile scripts/external-task-trigger.py  # syntax OK

Scope

This is a documentation and example-only contribution. It does NOT modify:

• AgentTeams core runtime
• Manager or Worker behavior
• Matrix protocol or CRD definitions
• Any existing test or production code

It demonstrates how an external backend (CRM, ticket system, workflow engine) can bridge structured jobs into the existing Manager-centered Matrix workflow.

Issue Reference

Addresses one item from Issue #1132: "Enterprise workflow feedback — programmable Manager dispatch, external trigger API, and governance primitives".

[oss-maintainer]

Summary

Adds a documented example + Python adapter (scripts/external-task-trigger.py) that bridges structured external job envelopes into AgentTeams via the existing Matrix/replay-task.sh Manager submission path, with task/trace IDs, validation, dry-run, and tests. Scope and structure are good and there are no credential issues, but there are a few correctness/accuracy items worth addressing before merge (see inline comments).

Findings

• [Warning] scripts/external-task-trigger.py:85 — dry-run returns a JSON-encoded string, so the output result field becomes nested JSON instead of the documented plain text.
• [Warning] scripts/external-task-trigger.py:205 — main()'s except is effectively unreachable; unexpected exceptions escape as a raw traceback, breaking the JSON output contract.
• [Warning] docs/.../external-task-trigger.md:60 — live mode depends on replay-task.sh, whose hardcoded openclaw gateway health check only works with the OpenClaw Manager runtime.
• [Info] docs/.../external-task-trigger.md:129 — [EXTERNAL_TASK] is a text convention, not a Manager protocol; worth stating explicitly.
• [Warning] docs/.../external-task-trigger.md:155 — docs claim 'Shell syntax and Python compilation checks' coverage that doesn't exist; subprocess/--no-wait paths are untested.

Suggestions

Return dry-run text directly from run_replay(); catch Exception in main() and emit a JSON error; add a runtime note (or runtime-aware readiness check) for live mode; soften the [EXTERNAL_TASK] wording to 'convention'; and align the 'Tests cover' list with what tests/test_external_task_trigger.py actually exercises.

---

Automated review by github-manager-bot

[oss-maintainer]

Dry-run mode returns a JSON-encoded string from run_replay(), so in run_task() (line ~148-150) the output's result field ends up containing a nested JSON string instead of the plain text shown in the documented output schema. Consider returning the dry-run text directly and letting run_task set the status.

[oss-maintainer]

run_task() already catches ValueError/FileNotFoundError/JSONDecodeError (line ~121) and the replay call is wrapped in a generic except Exception (line ~135), so this except block in main() is effectively unreachable for those types, while any other unexpected exception would surface as a raw Python traceback and break the script's JSON-output contract. Consider catching Exception here and emitting a JSON error object.

[oss-maintainer]

Live mode relies on scripts/replay-task.sh, which hardcodes an openclaw gateway health readiness check (see replay-task.sh line ~328), so it only works when the Manager runs the OpenClaw runtime. Since other Manager runtimes (qwenpaw/copaw) are common, the documented live mode may fail out of the box. Suggest adding a note about this limitation or making the readiness check runtime-aware.

[oss-maintainer]

The [EXTERNAL_TASK] envelope could be read as a Manager-understandable protocol, but the Manager has no special parser for this tag — it is a plain Matrix text message (as line 143 notes). Worth clarifying explicitly that this is a suggested human/LLM-readable convention, not a core AgentTeams protocol.

[oss-maintainer]

The docs claim the tests cover 'Shell syntax and Python compilation checks', but no such tests exist in tests/test_external_task_trigger.py. The suite also does not exercise the subprocess invocation of replay-task.sh or the --no-wait code path, leaving the integration boundary untested. Suggest updating the claims and/or adding coverage for those paths.