jira-api: API and Agent Channel

This plugin includes the existing API Actions and Workflow Triggers plus the jira-api/agent-issues Agent Channel. Existing action/trigger IDs, schemas and API authentication methods are unchanged. The additional Channel authentication is listed at plugin level; per-action authentication subsets are intentionally deferred. Use existing API Connections for Actions/Triggers and the Channel credentials below for agent conversations. No migration of unused standalone Channel installations is provided.

Jira bot Channel

Jira Cloud Agent Channel: jira-api/agent-issues. jira-bot names the dedicated customer account that writes comments; it does not imply a Forge/Connect application or alter generated Jira API auth.

Import jiraApiPlugin from the package root or from @dual-os/jira-api/executable. Definition-only composition uses jiraApiPluginBase from @dual-os/jira-api/definition.

Connection method bot-account: siteUrl, email, apiToken, webhookSecret. Use a dedicated Atlassian user or managed service account. For an unscoped user token, siteUrl is an HTTPS *.atlassian.net origin. Scoped tokens, including service-account tokens, use https://api.atlassian.com/ex/jira/<cloudId> instead. Both forms omit a trailing slash. The complete API base is frozen with the bot identity; another cloud ID requires a new activation. No environment credentials or automatic token renewal.

Definition settings: {}. Deployment settings: where (projectKeys, 1–1,000, and optional issueKeys), who (access, restricted recommended, and allowedSenderKeys, Atlassian account IDs) and when (respondTo: mentions or all_messages). Bot identity comes from authenticated /myself. Activation checks the bot credentials; Jira has no setup challenge and webhook configuration must be checked with a real mention after activation. Deactivation never edits the administrator's webhook.

Each issue ID is one group destination; no synthetic threads or reply nesting. Only created issues/comments are input. Real account mentions, or every message with all_messages, trigger responses; unaddressed comments are context, issues outside the chosen projects or issues are ignored, and own comments are ignored. REST reads check issue/comment access as the bot; role/group-restricted comments and service desk projects are excluded so public responses cannot disclose private comment input.

Operations: present_outcome, create_message, update_message, delete_message. Only the bot's own destination-issue comments can be edited/deleted. Delivery is at-most-once: Jira has no comment-create idempotency key, so uncertain completion is terminal rather than silently posting a duplicate. 429 is rate_limited; read/update/delete transport and 5xx failures are unavailable; ambiguous create transport/5xx/invalid-success responses are unknown_completion. No internal HTTP retries or redirects. Text uses ADF paragraphs, with choices appended to questions.

read_context returns the issue summary/description and at most 100 latest unrestricted comments in chronological order, bounded by the requested limit. For large conversations, the newest comments take priority over the opening description. ADF text, account mentions, lists, headings, tables, quotes, code, emoji and cards are decoded by protocol schemas. Mentions in admin webhook wiki text are classified from the corresponding REST ADF, so escaped examples and code do not address the Agent. Unsupported nodes fail closed. No attachments, reactions, activity, plans, nested threads, comment-update input, or JSM internal notes.

Admin webhook signatures are body-only HMAC SHA-256 (X-Hub-Signature). The event timestamp is signed with the body; there is no separate per-delivery signature timestamp, and the Channel enforces no age window. Replay identity uses the creation kind and immutable issue/comment IDs from the signed body; the unsigned X-Atlassian-Webhook-Identifier cannot change it. This deduplicates repeated creations without providing cryptographic freshness. The server owns durable replay receipts; this plugin stores no state. Separate created comments remain distinct even with equal timestamps.