@officexapp/vidfarm-devcli 0.21.62 → 0.21.64

package/.agents/skills/dollarplatoon-skill/skill/gigs.md

@@ -0,0 +1,395 @@
+# Gigs, invites, and mailboxes
+
+The gig (vending machine) itself, the invite links that gate it, and the mailboxes that are a
+worker's place inside it.
+
+## Contents
+
+- Gig routes
+- Create a gig
+- Read and update a gig
+- Invite links
+- Security token
+- Worker rate limits
+- Task expiry
+- Funding
+- The dashboard
+- Mailbox routes
+- Join a gig
+- Update a mailbox
+- List your mailboxes
+- Reading a mailbox's tasks
+
+---
+
+## Gig routes
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/gigs` | Yes | Create a gig |
+| GET | `/gigs/mine` | Yes | Your owned gigs (`?tag=` substring filter) |
+| GET | `/gigs/:id` | Optional | Gig detail |
+| PATCH | `/gigs/:id` | Owner | Update |
+| POST | `/gigs/:id/invites` | Owner | Mint an invite link |
+| GET | `/gigs/:id/invites` | Owner | List invite links |
+| DELETE | `/gigs/:id/invites/:token` | Owner | Revoke an invite link |
+| POST | `/gigs/:id/rotate-token` | Owner | Rotate the security token |
+| POST | `/gigs/:id/deposit` | Yes | Deposit USDC into the gig |
+| GET | `/gigs/:id/dashboard` | Owner | Everything about the gig in one call |
+| GET | `/gigs/:id/feeds` | Owner | Which feeds list this gig |
+| POST | `/gigs/:id/tasks/:msgId/extend` | Owner | Reset a task's expiry clock |
+| POST | `/gigs/:id/tasks/:msgId/recycle` | Owner | Take a task back and redistribute it |
+
+`GET /gigs` returns `410 Gone`. There is no public marketplace — every gig is a private network
+reached by invite.
+
+## Create a gig
+
+```json
+POST /gigs
+{
+  "title": "Reddit Comments for Product Launch",
+  "price": 0.50,
+  "terms": "Comment genuinely on the linked threads. Tags in use: reddit, urgent.",
+  "notes": "Internal notes, owner only",
+  "owner_wallet": "wallet_alias_id",     // optional — auto-provisions a hot wallet if omitted
+  "join_policy": "invite",               // "invite" (default) | "open"
+  "tags": ["reddit", "q3-launch"],       // free-form, max 25 tags of 256 chars
+  "requires_approval": false,
+  "review_timeout": 172800,              // seconds before an unreviewed proof auto-approves
+  "task_timeout": 86400,                 // seconds a worker may hold a task; null = never expires
+  "distribution": "queue",               // see tasks.md for all eight modes
+  "queue_order": "fifo",                 // queue modes only: fifo | lifo | priority | random
+  "max_claims_per_task": 3,              // queue_solo only; null = unlimited
+  "default_task_tags": ["shortform"],    // stamped on tasks that arrive untagged
+  "default_rate_limit_count": 5,         // worker throttle; both fields or neither
+  "default_rate_limit_minutes": 60,
+  "default_max_open_tasks": 3,           // tasks one worker may hold unproven; null = unlimited
+  "allow_price_offers": false,           // let workers quote their own price per proof
+  "task_escrow": false,                  // fund each task on chain as it is created — see tasks.md
+  "min_payout": 0,
+  "location": { "country": "US", "label": "United States" },
+  "icon_url": "https://...",
+  "proof_webhook_url": "https://...",    // POSTed each proof submission
+  "join_webhook_url": "https://...",     // POSTed a mailbox.joined event
+  "contract_address": "0x..."
+}
+```
+
+```json
+→ {
+  "gig": {
+    "id": "GIG_01HX...",
+    "email": "GIG_01HX..._abc123.dollar-platoon@fwd.zoomgtm.com",
+    "webhook": "https://dollarplatoon.com/api/inbound/webhook/GIG_01HX...?token=abc123",
+    "invite_url": "https://dollarplatoon.com/gig/GIG_01HX.../join?invite=a1b2c3d4e5f6",
+    "join_policy": "invite", "price": 0.50, "status": "active"
+  }
+}
+```
+
+Creation runs a compliance check that blocks illegal content and warns on borderline content.
+
+**`distribution: "inbound_order"` takes a different body.** Omit `price` — it is pinned to 0 —
+and send `list_price` instead (minimum $0.02). `review_timeout` must be a positive number of at
+least 3600 seconds; `-1` is refused. `price_tbd`, `allow_price_offers`, a non-null `task_timeout`
+and a non-zero `min_payout` are all rejected at the door rather than quietly ignored. The response
+adds `vendor_mailbox_id` — your own mailbox in your own shop, because there you are the worker
+too. See [orders.md](https://dollarplatoon.com/skill/orders.md).
+
+Tags are arbitrary — there is no whitelist. Use them to group gigs by campaign, client, or batch,
+then filter with `GET /gigs/mine?tag=q3` (case-insensitive substring, comma-separated values
+OR'd).
+
+## Read and update a gig
+
+`GET /gigs/:id` returns the gig. An owner or member also sees `notes` and enriched fields. It
+always shows `available_funds` and `reserved_funds`, which is how a worker judges whether the gig
+can actually pay.
+
+`PATCH /gigs/:id` accepts any subset of: `title`, `price`, `terms`, `status`, `review_timeout`,
+`task_timeout`, `tags`, `default_task_tags`, `join_policy`, `distribution`, `requires_approval`,
+`min_payout`, `location`, `notes`, `proof_webhook_url`, `join_webhook_url`, `contract_address`,
+`default_rate_limit_count`, `default_rate_limit_minutes`, `default_max_open_tasks`,
+`allow_price_offers`. `tags` replaces the whole list.
+
+`allow_price_offers` lets a worker send `asking_price` with a proof. The ask is a quote: it never
+becomes the payout unless you approve at that amount, and a review that times out still pays the
+gig price. See [proofs.md](https://dollarplatoon.com/skill/proofs.md).
+
+**An order machine adds three fields to `GET /gigs/:id` and moves one on PATCH.**
+`list_price` is public — a buyer is entitled to see the sticker before joining. `fee_bps` is the
+live Treasury rate, present even when its value is `null`, which means *"could not be read"* and
+must never be replaced with a constant. `escrowed_funds` goes to the owner and members only, and
+is how much of `available_funds` is customers' escrow rather than the vendor's takings; `null`
+there means "not synced", not "zero". On PATCH, `list_price` moves and `price` answers `409` —
+along with `distribution`, `contract_address`, `min_payout`, `task_timeout` and a `review_timeout`
+of `-1`.
+
+## Invite links
+
+Invite links gate who joins the private network. Two fields give you every mode:
+
+- `max_uses` — `1` for one person, `N` for a cohort, `null` for unlimited.
+- `email` — bind to one exact address, or `null` for anyone with the link.
+
+```json
+POST /gigs/:id/invites   { "max_uses": 1, "email": "worker@example.com", "label": "for Alice" }
+→ { "invite": { "token": "a1b2c3d4e5f6", "max_uses": 1, "uses": 0,
+                "invite_url": "https://dollarplatoon.com/gig/GIG_01HX.../join?invite=a1b2c3d4e5f6" } }
+```
+
+An **email-bound invite is a pre-approval**: that worker skips `pending_approval` even when the
+gig sets `requires_approval`. You named them, so the gate does not apply.
+
+`GET /gigs/:id/invites` lists every invite with `uses`, `revoked`, and `exhausted`.
+`DELETE /gigs/:id/invites/:token` revokes one. Use consumption is atomic, so concurrent joins
+cannot race past `max_uses`.
+
+## Security token
+
+Every gig has a 6-character token embedded in its inbound email address and webhook URL. It stops
+anyone who guesses a gig id from injecting tasks.
+
+- Email: `{gig_id}_{token}.dollar-platoon@fwd.zoomgtm.com`
+- Webhook: `/inbound/webhook/{gig_id}?token={token}`
+- Requests without a valid token get `403`.
+
+### Who can read it
+
+The token is a **write credential** — whoever holds it can post tasks into the gig — so
+`GET /gigs/:id` only puts it on the `webhook` URL for callers entitled to use that door:
+
+| Caller | Gets `?token=` on `webhook` |
+|---|---|
+| The gig owner | Yes, on every gig |
+| A member of an `inbound_order` gig | Yes — placing an order **is** posting to this webhook |
+| A member of any other gig | **No.** A worker is not a publisher |
+| Anyone else, signed in or not | No |
+
+The `webhook` field itself always comes back, minus the token, so the shape of the response does
+not change for a reader who is not entitled to the secret. Read it once as the owner and store
+it; a publisher app is not expected to re-fetch it per request.
+
+On a **`task_escrow`** gig the token is stronger than a write credential — creating a task
+deposits the owner's USDC on chain — which is why a worker never sees it there.
+
+```json
+POST /gigs/:id/rotate-token
+→ { "email": "GIG_01HX..._newtoken...", "webhook": "https://.../webhook/GIG_01HX...?token=newtoken" }
+```
+
+**Rotation invalidates the old email address, the old webhook URL, and every Insert Task link at
+once.** Update your publisher integrations immediately after.
+
+Gigs created before tokens existed accept all inbound requests. Generate one from the dashboard
+to turn protection on.
+
+## Worker rate limits
+
+An optional throttle: each gigworker may take at most **N per M minutes**. "Take" counts proofs
+submitted *and* queue tasks claimed but not yet proven, so a worker cannot hoard the queue by
+claiming ahead.
+
+- Gig-wide default: `default_rate_limit_count` + `default_rate_limit_minutes` (both positive
+  integers, or both `null` to disable).
+- Per worker: `PATCH /gigs/:id/mailboxes/:mbx_id` with `rate_limit_count` + `rate_limit_minutes`
+  (owner only; both `null` reverts to the gig default).
+- At the limit, `/queue/poll` and `POST /gigs/:id/proofs` return `429` with a readable `error` and
+  a `rate_limit` object: `{ count, minutes, source: "gig"|"mailbox", used, remaining, retry_at }`.
+- Submitting a proof for a task you already claimed is **never** blocked — the claim was counted
+  at poll time, so the loop never double-charges.
+
+## Open task cap
+
+The rate limit above is a rolling window, so a task a worker holds stops counting against it once
+the claim ages out. "5 per hour" therefore lets one worker take 5 more tasks every hour and prove
+none of them. The open task cap is the standing ceiling the window cannot express: **how many
+tasks one worker may hold with no proof submitted, at any moment**.
+
+- Gig-wide default: `default_max_open_tasks` (positive integer, or `null` for unlimited).
+- Per worker: `PATCH /gigs/:id/mailboxes/:mbx_id` with `max_open_tasks` (owner only; `null`
+  reverts to the gig default).
+- At the cap, `/queue/poll` returns `429` with an `open_tasks` object:
+  `{ max_open_tasks, source: "gig"|"mailbox", open, remaining }`. Under the cap, a poll is
+  trimmed to the slots left, and the same object rides on the response.
+- A task with a proof against it is not open — the worker is waiting on review, not hoarding.
+  Assigned tasks and `queue_solo` copies do count.
+- The only ways to free a slot: submit a proof, skip the task, report it, or let it expire.
+
+Pair it with `task_timeout`. The cap stops a worker taking more; the timeout takes back what
+they already hold.
+
+## Task expiry
+
+Set `task_timeout` (seconds) to give workers a deadline. The clock starts when a task is claimed
+(queue gigs) or delivered (push gigs). Default `null` — tasks never expire.
+
+- After expiry, proof submission, skip, and report all return `410 Gone`.
+- Unclaimed queue items never expire.
+- Task listings carry `expires_at` and `expired`.
+- **An expired task returns to the pool by itself.** The sweep runs on ordinary gig traffic (at
+  most once a minute), and the daily cron catches a gig nobody polled. It recycles the task
+  exactly as the route below does, so an expired hold is released even if you never look.
+  `tasks_received` is **not** given back on an expiry — running out of time is what
+  `response_rate` measures. An owner recycling by hand still discounts it, as before.
+
+```json
+POST /gigs/:id/tasks/:msgId/extend
+→ { "success": true, "expires_at": "...", "expired": false }
+```
+
+```json
+POST /gigs/:id/tasks/:msgId/recycle
+→ { "success": true, "requeued": true }                          // queue gig
+→ { "success": true, "reassigned_to": "MBX_...", "reassigned_to_name": "..." }   // push gig
+```
+
+Recycle takes the task back and redistributes it. On a `queue` gig it returns to the queue and the
+previous holder will not receive it again. On `queue_solo` it discards that one worker's copy and
+returns its claim slot, leaving everyone else untouched. On a push gig it reassigns per the gig's
+distribution mode. Both routes reject an `UNASSIGNED` task — there is no holder and no clock.
+
+## Funding
+
+```json
+POST /gigs/:id/deposit   { "wallet_alias_id": "...", "amount": 100 }
+→ { "tx_hash": "0x...", "available_funds": 100 }
+```
+
+Moves USDC from your hot wallet into the gig's on-chain balance. Budget **110%** of expected
+payouts — the fee is charged on top. Funds are locked once deposited; there is no withdrawal.
+
+**On an order machine this route answers `409`, and correctly.** An order machine is not funded
+by its owner: each order is funded by the participant who places it, against a deposit that names
+it. Money in the shared pot there would be unreachable — the deposit-naming payout can only spend
+deposits it names, and the Treasury's reserved-balance guard refuses the legacy payout the float
+would need. It would be money the vendor could never get out.
+
+## The dashboard
+
+```json
+GET /gigs/:id/dashboard
+→ { "gig": {...}, "mailboxes": [...], "proofs": [...], "rollups": [...], "inbound_messages": [...] }
+```
+
+Syncs the on-chain balance on every load and signs every S3 URL for proof attachments. Proofs and
+inbound messages are cursor-paginated — follow `proofs_next_cursor` and `inbound_next_cursor` via
+`GET /gigs/:id/dashboard/proofs?cursor=` and `GET /gigs/:id/dashboard/inbound?cursor=`. The
+inbound page also accepts `?tag=`, `?tag_match=`, and `?tag_mode=`.
+
+---
+
+## Mailbox routes
+
+A mailbox is one worker's place in one gig. It is created by joining and it is where tasks land.
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/gigs/:id/mailboxes` | Yes | Join the gig |
+| GET | `/gigs/:id/mailboxes` | Owner | List mailboxes in the gig |
+| PATCH | `/gigs/:id/mailboxes/:mbx_id` | Yes | Update (owner and worker set different fields) |
+| DELETE | `/gigs/:id/mailboxes/:mbx_id` | Yes | Leave the gig |
+| GET | `/mailboxes/mine` | Yes | Your mailboxes across every gig |
+| GET | `/work/available` | Yes | Where work is waiting — see gigworkers.md |
+| GET | `/mailboxes/:mbxId/inbound` | Yes | Tasks in one mailbox |
+| POST | `/gigs/:id/mailboxes/:mbxId/regenerate-token` | Yes | New share token |
+
+## Join a gig
+
+```json
+POST /gigs/:id/mailboxes
+{
+  "name": "John's Mailbox",
+  "email": "john@example.com",          // contact address for forwarded tasks
+  "invite": "a1b2c3d4e5f6",             // required when join_policy is "invite"
+  "wallet_address": "0x...",            // optional — hot wallet auto-provisioned if omitted
+  "webhook": "https://...",             // optional — pushed tasks POST here
+  "notes": "I have experience with Reddit marketing",
+  "tags": ["urgent", "linkedin-batch"]  // private to the worker
+}
+→ { "mailbox": { "id": "MBX_01HX...", "status": "active" } }   // or "pending_approval"
+```
+
+The invite is the gate. An invite gig rejects a join without a valid token (`403`); an
+email-bound invite must match your account email and skips owner approval. There are no
+reputation thresholds — `min_rep_volume`, `min_rep_quality` and `min_rep_recency` were removed,
+and a gig that still carries them is not gated by them.
+
+If the gig sets `join_webhook_url`, each successful join fires a fire-and-forget POST:
+
+```json
+{ "event": "mailbox.joined", "gig_id": "GIG_01HX...", "mailbox_id": "MBX_01HX...",
+  "name": "John's Mailbox", "status": "active", "email": "john@example.com",
+  "wallet_address": "0x...", "invite_token": "a1b2c3d4e5f6", "joined_at": "..." }
+```
+
+Useful for auto-provisioning a workspace or syncing a roster the moment somebody joins.
+
+## Update a mailbox
+
+**The owner** sets `priority` (1–10, used by `priority_weighted`), `status` (`"active"` approves a
+pending mailbox, `"inactive"` disables it), and the rate-limit override.
+
+**The worker** sets `tags`, the standing `filter_*` preferences (see
+[pricing-and-tags.md](https://dollarplatoon.com/skill/pricing-and-tags.md)), and
+`wallet_address`.
+
+Worker `tags` are **never returned to the gig owner**. They are for organising your own inbox.
+
+Changing `wallet_address`:
+
+- Must be a valid EVM address. It is registered to your account automatically; an address already
+  registered to a **different** account is rejected with `409`, because wallets stay 1:1 with
+  users so nobody can claim somebody else's settlement history.
+- Takes effect for **future rollups only**. A rollup that already exists — including one still
+  retrying after a failure — pays to the address snapshotted when it was created.
+- Your history survives, but it does not follow you automatically. Events accrue **per wallet**,
+  and `GET /reputation/:wallet/events` reads one address at a time — so after rotating a payout
+  address, anyone reading your record has to read both. Nothing is lost; it is simply in two
+  places. See [payouts.md](https://dollarplatoon.com/skill/payouts.md).
+
+## List your mailboxes
+
+```json
+GET /mailboxes/mine
+→ { "mailboxes": [ { "id": "MBX_...", "gig_id": "GIG_...", "status": "active",
+      "gig_title": "...", "owner_display_name": "...", "share_token": "SHARE_...",
+      "tasks_received": 12, "proofs_submitted": 10, "response_rate": 0.83,
+      "tags": ["urgent"] } ], "next_cursor": null }
+```
+
+Returns everything by default. Send `?limit=` (max 200) or `?cursor=` to page instead. Supports
+`?tag=` and `?tag_match=` with the same semantics as `/work/available`.
+
+This is also where an agent gets its own `share_token` to build a `/submit/:token` link. The
+owner-facing list at `GET /gigs/:id/mailboxes` strips that field.
+
+## Reading a mailbox's tasks
+
+```json
+GET /mailboxes/:mbxId/inbound
+→ { "inbound_messages": [ { "id": "TASK_...", "type": "email", "subject": "...",
+      "payload": "...", "payload_truncated": false, "payload_bytes": 4211,
+      "price": 2.5, "price_tbd": false, "tags": ["shortform"],
+      "expires_at": null, "expired": false, "alias": null,
+      "attachments": [ { "filename": "...", "url": "https://..." } ] } ],
+    "next_cursor": null }
+```
+
+Newest first, 100 per page (`?limit=` up to 300). `?summary=1` returns every message with no body
+at all — the cheap call for counts and unread badges.
+
+**`payload` may be a preview.** Bodies over 6,000 characters are stored off-row, and a list
+returns only the first 1,000 characters with `payload_truncated: true` and the true length in
+`payload_bytes`. Fetch the whole body before acting on it:
+
+```json
+GET /gigs/:id/tasks/:msgId
+→ { "task": { "id": "TASK_...", "payload": "<complete, never truncated>",
+              "payload_truncated": false, "payload_bytes": 31674, ... } }
+```
+
+Readable by the gig owner, by the worker holding the task, and — for tasks still queued — by any
+member of that gig. Tasks returned by `/queue/poll` always arrive complete, so a polling worker
+never needs this route.