@atollhq/skill-codex 0.4.32 → 0.4.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atollhq/skill-codex",
-  "version": "0.4.32",
+  "version": "0.4.34",
   "description": "Install the Atoll project management integration for Codex CLI",
   "bin": {
     "skill-codex": "bin/install.mjs"
@@ -18,7 +18,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/atollhq/atoll.git",
+    "url": "git+https://github.com/antons-agents/atoll.git",
     "directory": "packages/skill-codex"
   },
   "dependencies": {

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
 

package/skill/references/local-runner.md

@@ -90,3 +90,78 @@ are blocked while a current job exists. Refresh, config validation, and Codex
 preflight are non-destructive; there is no model retry or cleanup button.
 A UI port or asset failure does not stop headless execution. Do not proxy this
 loopback interface to another host. Service installation remains separate.
+
+### macOS service and lifecycle
+
+Install an explicit user service only when unattended operation is required:
+
+```bash
+atoll-runner --profile agent-a service install
+atoll-runner --profile agent-a service install --ui --ui-port 4735
+atoll-runner --profile agent-a service status
+atoll-runner --profile agent-a service uninstall
+```
+
+The service is macOS-only. Install writes an atomic user-owned `0600` plist
+under `~/Library/LaunchAgents/` with canonical Node and runner entry paths,
+the selected profile, `run`, and optional loopback UI arguments. It contains no
+environment variables, API keys, Codex or lease tokens, shell command,
+checkout path, or worktree path. Unknown or changed plists fail closed.
+Package installation is passive and never installs or starts the service. Use
+uninstall, package upgrade, `doctor`, then install for an upgrade. Uninstall
+removes only the exact owned plist and leaves journals, tokens, logs, branches,
+and worktrees. Status and uninstall validate the local plist and do not require
+profile credentials; install remains authenticated.
+
+SIGINT/SIGTERM closes the process-local intake gate immediately. The current
+child drains for at most 30 seconds; TERM and then KILL after 10 seconds are
+sent only when the journaled PID still has the same process-start identity. A
+wall-clock event-loop gap above 30 seconds is a possible wake. The child is
+stopped, durable lease state is reconciled, and intake reopens only after that
+pass. A wake may release a worker only to finish an already durable result;
+stop never releases a worker. No hosted pause request is sent. Existing-wire
+response failures are bounded as `RUNNER_PROTOCOL_MISMATCH` and keep pending
+mutation journals available for replay.
+
+### Opt-in real local smoke
+
+This developer harness is available only from an Atoll source checkout. It is
+not included in the installed npm CLI. After deterministic checks, use a clean
+loopback fixture profile with no current or conflicting retained job, and run
+from `packages/cli`:
+
+Loopback remains the normal default. Repository owners may also run one bounded
+production validation turn from a clean Atoll source checkout. This mode requires
+an exact canonical production origin, organization, project, authenticated agent,
+issue, runner host and instance, and the live project repository mapping's opaque
+`repo_ref` plus repository full name. The supplied `repo_ref` is checked against
+live issue routing and must never be hard-coded. The smoke derives the canonical
+source root from its own script, requires a clean source checkout, rebuilds the
+candidate in the invocation, and records the source root, source `HEAD`, and
+worker-entry SHA-256 in bounded mode-`0600` evidence. Exact production admission
+performs zero presence `PUT`/upsert operations for either connected or
+disconnected targets. Registration and refresh belong to separate operator setup
+outside this invocation. The invocation reads the connected runner identity
+before claim and rechecks it immediately before the claim; a disconnected target
+fails closed. The runner does not explicitly select a model. The Codex runtime
+and local Codex configuration supply model selection. `@openai/codex` and
+`@openai/codex-sdk` are pinned to package/runtime version `0.153.4`; this
+version is not a model name. Use the internal AH-2088 production smoke
+runbook for the owner-only command and cleanup procedure.
+
+
+```bash
+cd packages/cli && bun run build
+ATOLL_RUNNER_MANUAL_SMOKE=1 bun run runner:manual-smoke -- \
+  --profile agent-a --issue issue-uuid --repository /path/to/checkout \
+  --timeout-ms 300000 --evidence /absolute/path/evidence.json
+```
+
+The smoke runs one real Codex turn through the existing runner. It creates and
+retains its owned local branch and worktree while preserving the primary
+checkout, and writes bounded fixture issue, host, generation, branch/worktree,
+base/head SHA, thread, terminal, and time evidence outside the checkout. A
+timeout is always failure; retained journal state is authoritative. It never
+pushes or deletes retained state, publishes, deploys, or installs a service.
+Codex Desktop visibility is a separate operator observation; deterministic tests
+use a fake SDK.