@atollhq/skill-codex 0.4.33 → 0.4.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atollhq/skill-codex",
-  "version": "0.4.33",
+  "version": "0.4.34",
   "description": "Install the Atoll project management integration for Codex CLI",
   "bin": {
     "skill-codex": "bin/install.mjs"

package/skill/SKILL.md

@@ -44,6 +44,18 @@ Read only the references required for the current task:
 - Request and response fields, enums, and validation:
   [api-fields.md](references/api-fields.md)
 
+Outbound webhooks support optional Standard Webhooks signing with a receiver
+supplied canonical `whsec_` secret. Read the webhook references before creating
+or updating a destination; signing secrets are write-only and automatic retry
+delivery ids remain stable. Grok Automations and Hermes support this receiver
+contract; see the integration reference for their setup and event caveats.
+
+Agent creation can select an allowlisted built-in icon with `avatarPreset`.
+Manage an existing guest agent icon through the member avatar endpoint: upload
+a custom image with `POST`, select a built-in preset with `PATCH`, or remove it
+with `DELETE`. Read [api-endpoints.md](references/api-endpoints.md) and
+[api-fields.md](references/api-fields.md) for the exact contract and limits.
+
 For automation rule V1 actions (including create issue and send webhook), explicit project or
 organization scope, CI create-or-webhook rules, scheduled `schedule.issue_time`
 rules, event conditions, validation, safe

package/skill/references/api-endpoints.md

@@ -634,10 +634,12 @@ deferred; parent deletion returns after durable queueing.
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | POST | `/api/orgs/{id}/members/{memberId}/avatar` | Upload avatar to public `avatars` bucket (multipart, max 2MB, JPEG/PNG/WebP/GIF) |
+| PATCH | `/api/orgs/{id}/members/{memberId}/avatar` | Select an allowlisted built-in agent icon preset (`{ preset }`) |
 | DELETE | `/api/orgs/{id}/members/{memberId}/avatar` | Remove avatar |
 
 Members may manage their own avatar; organization owners/admins may manage
-another member only inside the same path organization. Cross-organization
+another member only inside the same path organization. A human may also manage
+a guest agent avatar when they created the agent or own the personal agent. Cross-organization
 caller or target IDs return `404`. Upload returns
 `{ "member": { "id": "...", "avatar_url": "..." } }` with no other member
 metadata. Avatar updates use compare-and-set semantics: concurrent changes
@@ -849,9 +851,30 @@ failed without executing its actions.
 | POST | `/api/webhooks/{id}/redeliver/{deliveryId}` | Redeliver a past payload (owner/admin) |
 | POST | `/api/webhooks/{id}/test` | Send ping test event (owner/admin) |
 
-URL must be an HTTPS DNS hostname. IP literals, `localhost`, and `.local` hosts are rejected at creation; delivery refuses non-public DNS results and does not follow redirects. Returns webhook record plus `secret` for HMAC verification. Store the secret immediately; it is shown only once. Later lists expose only `destination_display` such as `https://example.com/…`.
-
-Payload schema version `2` is allowlisted and omits descriptions, comment bodies, and raw change values. Delivery requests include `X-Atoll-Signature`, `X-Atoll-Signature-Version`, versioned `X-Atoll-Signatures`, and `X-Atoll-Delivery-Id`. Delivery history returns safe status, `error_code`, and retry timing only—not payloads, receiver response bodies, or raw errors. Atoll retries network failures and 5xx responses after 5s and 30s, then records `status: retry_pending` with `next_retry_at`; an internal cron drains due retries every 15 minutes.
+URL must be an HTTPS DNS hostname. IP literals, `localhost`, and `.local` hosts are rejected at creation; delivery refuses non-public DNS results and does not follow redirects. Returns webhook record plus `secret` for HMAC verification. Store the secret immediately; it is shown only once. Later lists expose only `destination_display` such as `https://example.com/…`; Standard Webhooks exposes only its configured boolean.
+
+Automation action deliveries use payload schema version `3` with current
+tenant-scoped issue and project fields. Subscription broadcasts and `ping`
+remain schema version `2`; existing queued payloads retain their stored schema
+and content. V3 includes safe sorted `trigger.changedFields`, optional
+privacy-safe artifact counts, and `project: null` for projectless issues. An
+artifact summary is omitted when its lookup fails, returns an invalid type, or
+cannot complete within the bounded 1,000-row pagination limit. CI
+actions set `issue: null`, `changedFields: []`, and retain only useful CI fields.
+Both versions omit descriptions, comment bodies, and raw change values. Delivery
+requests include `X-Atoll-Signature`, `X-Atoll-Signature-Version`, versioned
+`X-Atoll-Signatures`, `X-Atoll-Delivery-Id`, and `Idempotency-Key`. Standard
+Webhooks adds `webhook-id`, `webhook-timestamp`, and
+`webhook-signature: v1,<base64>`; the signature covers
+`deliveryId.timestamp.rawBody` with the decoded receiver key. Automatic retries
+preserve delivery id/key with fresh timestamps/signatures; manual redelivery
+uses new values, preserves v3 body content, and rewrites only legacy v2 automation bodies that contain
+`data.deliveryId`. Delivery history returns safe status, `error_code`, and retry
+timing only—not payloads, receiver response bodies, or raw errors. Atoll makes
+one 30-second request attempt per invocation. Network failures and 5xx
+responses are recorded as `status: retry_pending` with `next_retry_at`; an
+internal cron drains due retries every 15 minutes. A 2xx response proves
+acceptance only.
 
 ## Private Inbound Email Inbox
 
@@ -905,7 +928,7 @@ Google Chat mention cards include the task title, a safely formatted plain-text
 | GET | `/api/orgs/{id}/agents` | List agents (owner/admin) |
 | GET | `/api/orgs/{id}/agents/workforce` | Read a bounded workforce projection; org owners/admins may list all agents, project admins must pass `?projectId=...`, and individual owners may read their own agents |
 | GET | `/api/orgs/{id}/agents/manageable` | List manageable agents with visible project IDs, named accessible projects, heartbeat policy status/focus summary, API-key usage metadata, and aggregate active-key/OAuth activity |
-| POST | `/api/orgs/{id}/agents` | Create org agent (`{ name, role?, setupScoped? }`), project-scoped agent (`{ name, projectIds }` or legacy `{ name, projectId, projectIds? }`), or personal agent (`{ name, personal: true }`); key-minting responses include one-time `apiKey` and stable `apiKeyId` (`oauthOnly` omits both) |
+| POST | `/api/orgs/{id}/agents` | Create org, project-scoped, or personal agent; optional `avatarPreset` accepts only a built-in agent icon ID, and key-minting responses include one-time `apiKey` and stable `apiKeyId` (`oauthOnly` omits both) |
 | DELETE | `/api/orgs/{id}/agents/{agentId}` | Revoke manageable agent |
 | PATCH | `/api/orgs/{id}/agents/{agentId}/projects` | Replace project access for a manageable non-personal agent |
 | POST | `/api/orgs/{id}/projects/{projectId}/agents` | Grant selected manageable agents access to a project |

package/skill/references/api-fields.md

@@ -153,7 +153,7 @@ Request bodies accept **camelCase** (`assigneeId`, `projectId`). Snake_case also
 
 ## Avatar Upload Response
 
-Successful `POST /api/orgs/{id}/members/{memberId}/avatar` requests return
+Successful `POST` uploads and `PATCH` preset selections at `/api/orgs/{id}/members/{memberId}/avatar` return
 `200` with exactly:
 
 ```json
@@ -244,7 +244,7 @@ Creation endpoints may return `402` when an org reaches its billing plan limit:
 
 ## Agent Fields
 
-Create org-wide agents with `{ "name": "...", "role": "member", "setupScoped": false }`; org-wide creation is owner/admin-only. Create project-scoped agents with non-empty `projectIds`, for example `{ "name": "...", "projectIds": ["project-uuid"] }`; `projectId` remains accepted as a legacy/default-project alias and is merged with `projectIds`. Project-scoped agents are created as guests, and human members may only scope them to projects they can access. Create personal agents with `{ "name": "...", "personal": true }`; personal agents inherit their human owner's project access and reject explicit `projectId`/`projectIds`.
+Create org-wide agents with `{ "name": "...", "role": "member", "setupScoped": false }`; org-wide creation is owner/admin-only. Create project-scoped agents with non-empty `projectIds`, for example `{ "name": "...", "projectIds": ["project-uuid"] }`; `projectId` remains accepted as a legacy/default-project alias and is merged with `projectIds`. Project-scoped agents are created as guests, and human members may only scope them to projects they can access. Create personal agents with `{ "name": "...", "personal": true }`; personal agents inherit their human owner's project access and reject explicit `projectId`/`projectIds`. Any create form may include an allowlisted `avatarPreset` ID. Arbitrary URLs are rejected. Existing agent presets are changed with `{ "preset": "codex" }` on the avatar PATCH endpoint.
 
 Key-minting agent creation responses contain the one-time raw `apiKey` and its stable `apiKeyId`. Creation with `oauthOnly: true` omits both fields.
 
@@ -539,7 +539,11 @@ characters), and legacy `close_issue` (omit `value`, targets the valid `done` ke
 The destination must be enabled, same-org, and purpose `automation` or `both`.
 Queued transport retries do not re-run the automation action. Activity exposes
 `webhook_delivery_id` plus safe latest-attempt `webhook_delivery` state.
-Manual redelivery uses a new header and payload delivery ID.
+Automation payloads use schema v3 with current tenant-scoped project and issue
+fields, safe sorted `trigger.changedFields`, and optional artifact counts; CI
+uses `issue: null` and `changedFields: []`. Subscription broadcasts and `ping`
+remain schema v2. Manual redelivery uses a new header and rewrites a payload
+delivery ID only for legacy v2 automation bodies that contain that field.
 Already satisfied assignments, priorities, statuses, and label relationships
 succeed without duplicate mutation events. Invalid references still fail.
 Unsupported action types or malformed values return `400` and are not saved.
@@ -752,10 +756,10 @@ reject `position`.
 
 ## Webhook Fields
 
-Bearer secrets must contain only printable ASCII characters. Switching from none to Bearer requires a token and returns HTTP 400 if it is missing.
+Bearer secrets must contain only printable ASCII characters. Switching from none to Bearer requires a token and returns HTTP 400 if it is missing. The optional `standard_webhooks` setting accepts a receiver-supplied `whsec_` secret; it is write-only and must be canonical standard Base64 after the prefix, decoding to 24-64 bytes. Lists expose only `standard_webhooks.configured`.
 
 `PATCH /api/webhooks/{id}` preserves omitted fields. A blank or omitted Bearer
-secret preserves the token; `auth.type: none` clears it. URL/auth changes create
+secret preserves the token; `auth.type: none` clears it. URL/auth/Standard signing changes create
 a new private destination version; pending deliveries retain their pinned version.
 
 ```json
@@ -764,13 +768,17 @@ a new private destination version; pending deliveries retain their pinned versio
   "events": ["issue.created", "issue.updated"],
   "enabled": true,
   "purpose": "subscription",
-  "auth": { "type": "none" }
+  "auth": { "type": "none" },
+  "standard_webhooks": {
+    "enabled": true,
+    "secret": "whsec_<canonical-standard-base64>"
+  }
 }
 ```
 
-URL must be an HTTPS DNS hostname. IP literals, `localhost`, and `.local` hosts are rejected at creation; delivery refuses non-public DNS results and does not follow redirects. The create response includes a `secret` for HMAC signature verification. Store it immediately; it is shown only once. Use purpose `automation` or `both` with `auth: { "type": "bearer", "secret": "..." }` for automation destinations; responses expose only `auth.type` and `auth.configured`.
+URL must be an HTTPS DNS hostname. IP literals, `localhost`, and `.local` hosts are rejected at creation; delivery refuses non-public DNS results and does not follow redirects. The create response includes an Atoll-generated `secret` for HMAC signature verification. Store it immediately; it is shown only once. This is distinct from the receiver-supplied Standard Webhooks `whsec_` secret. Use purpose `automation` or `both` with `auth: { "type": "bearer", "secret": "..." }` for automation destinations; responses expose only `auth.type` and `auth.configured`.
 
-List responses include `destination_display` and a deprecated `url` compatibility field containing only the origin plus `/…`. Payload schema version `2` is allowlisted. Delivery requests include `X-Atoll-Signature`, `X-Atoll-Signature-Version`, versioned `X-Atoll-Signatures`, and `X-Atoll-Delivery-Id`. Delivery history includes `delivery_id`, `status`, `status_code`, `error_code`, `delivered_at`, and `next_retry_at`, never payloads, receiver response bodies, or raw errors.
+List responses include `destination_display` and a deprecated `url` compatibility field containing only the origin plus `/…`. Automation action payloads use schema version `3` with current tenant-scoped project and issue fields; subscription broadcasts and `ping` remain schema version `2`. Delivery requests include `X-Atoll-Signature`, `X-Atoll-Signature-Version`, versioned `X-Atoll-Signatures`, `X-Atoll-Delivery-Id`, and `Idempotency-Key`. When Standard Webhooks is enabled, they also include `webhook-id`, `webhook-timestamp`, and `webhook-signature`. Delivery history includes `delivery_id`, `status`, `status_code`, `error_code`, `delivered_at`, and `next_retry_at`, never payloads, receiver response bodies, or raw errors.
 
 ## Private Inbox Fields
 

package/skill/references/integrations-and-api.md

@@ -207,14 +207,55 @@ Config sessions and unused manual connect tokens expire after 10 minutes. Sessio
 
 `POST /api/webhooks` creates outbound webhooks. Receiver URLs must be HTTPS DNS hostnames; Atoll rejects IP literals, `localhost`, `.local` hosts, URL credentials, and fragments at creation. Delivery also resolves DNS and refuses private, loopback, link-local, documentation, multicast, and other non-public addresses; redirects are not followed.
 
-Webhook creation returns a raw `whsec_...` secret once. Delivery requests include:
+Webhook creation returns an Atoll-generated signing `secret` once. Store it
+immediately; it is distinct from the receiver-supplied Standard Webhooks
+`whsec_` secret. Delivery requests include:
 
 - `X-Atoll-Signature`: `sha256=` plus an HMAC-SHA256 over the raw body, keyed by the SHA-256 hex digest of the raw secret.
 - `X-Atoll-Signature-Version`: the primary signing-key version.
 - `X-Atoll-Signatures`: versioned signatures during a bounded key-overlap window.
 - `X-Atoll-Delivery-Id`: stable delivery id for receiver-side deduplication.
-
-Webhook administration is owner/admin only. Lists return an origin-only `destination_display`; paths, queries, and signing material are never returned. Payload schema version `2` is allowlisted and omits descriptions, comment bodies, and raw change values. Delivery rows expose safe `delivery_id`, `status`, `status_code`, `error_code`, and retry timing, but not payloads, receiver response bodies, or raw errors. Network failures and 5xx responses retry quickly in-process, then persist `status: retry_pending` with `next_retry_at`; an internal drain retries due deliveries every 15 minutes.
+- `Idempotency-Key`: present on every outbound delivery; it is the same logical delivery id across automatic retries, while manual redelivery uses a new id and key.
+- Optional Standard Webhooks signing adds `webhook-id`, `webhook-timestamp`, and `webhook-signature: v1,<base64>` using the receiver's canonical `whsec_` secret (24-64 decoded bytes). The signature covers `deliveryId.timestamp.rawBody`. A 2xx response proves acceptance only.
+
+
+
+### Receiver setup
+
+Grok Automations supports this Standard Webhooks option. Configure an
+`automation` destination with the receiver-supplied `whsec_` value from Grok.
+Grok validates `webhook-id`, `webhook-timestamp`, and
+`webhook-signature: v1,<base64>` within a five-minute timestamp window; HTTP
+202 means accepted for processing, not completed.
+
+Hermes supports the same Standard Webhooks `whsec_` verification on a public
+HTTPS `/webhooks/<route>` endpoint. Configure the Hermes receiver route/filter
+with `events: ["automation.action"]`; this is a receiver setting. In Atoll, set
+the destination `purpose` to `automation` (or `both`) and trigger it with an
+explicit `send_webhook` action; the Atoll destination `events` field does not
+select automation actions. Hermes should allowlist and render these v3 fields
+when present: `data.project`, `data.issue`, `data.automation.ruleId`,
+`data.automation.ruleName`, `data.trigger.eventType`, and
+`data.trigger.changedFields`. Issue payloads also include the current persisted
+`id`, optional `identifier` and `url`, `title`, `status`, `priority`, `assigneeId`,
+`updatedAt`, and an optional privacy-safe `artifacts` count. CI payloads set
+`data.issue` to null and retain only the useful `ci` fields, so handle CI events
+separately. Hermes can use `webhook-id` for one-hour deduplication. A 2xx
+response is receiver acceptance, not agent completion. No live Hermes receiver
+test was run; this setup guidance is based on source compatibility.
+
+Webhook administration is owner/admin only. Lists return an origin-only
+`destination_display`; paths, queries, and signing material are never returned.
+Automation action payloads use schema version `3`; subscription broadcasts and
+`ping` remain schema version `2`. Existing queued payloads retain their stored
+schema and content. Artifact summaries are omitted when lookup fails, data is
+invalid, or counting cannot complete within the bounded 1,000-row pagination
+limit. Both versions omit descriptions, comment bodies, and raw change values.
+Delivery rows expose safe `delivery_id`, `status`, `status_code`,
+`error_code`, and retry timing, but not payloads, receiver response bodies, or
+raw errors. Each invocation makes one 30-second request attempt. Network
+failures and 5xx responses persist `status: retry_pending` with
+`next_retry_at`; an internal drain retries due deliveries every 15 minutes.
 
 ### GitHub delivery context