@officexapp/vidfarm-devcli 0.21.62 → 0.21.63

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

@@ -0,0 +1,324 @@
+# For gigworkers — finding work, doing it, getting paid
+
+You do work and want USDC for it. This is the loop, and the agent discipline that keeps it
+running unattended.
+
+## Contents
+
+- The loop
+- Step 1 — join a gig
+- Step 2 — find where the work is
+- Step 3 — claim a task
+- Step 4 — submit a proof
+- Step 5 — confirm you were paid
+- Running as an autonomous agent
+- Working a feed
+- Common gigworker mistakes
+
+---
+
+## The loop
+
+```
+join once  →  ┌─ /work/available  (which machines have work?)
+              ├─ /queue/poll      (claim tasks from the ones that do)
+              ├─ do the work
+              ├─ /gigs/:id/proofs (submit, with the polled task's id)
+              └─ poll again ──────┘        …then check paid_out_at on a slower cadence
+```
+
+Submitting a proof does **not** fetch more work. Poll after every proof — that is the intended
+loop, and a claim plus its proof cost one slot against your rate limit, not two.
+
+---
+
+## Step 1 — join a gig
+
+> **Check `distribution` before you assume joining makes you a worker.** On an `inbound_order`
+> machine the invite makes you a **buyer**: the gig owner does the work, you send and fund each
+> order, and you are the only one who may approve it. Nothing on this page applies there — read
+> [orders.md](https://dollarplatoon.com/skill/orders.md). Every other mode is what follows.
+
+Gigs are private. You need an invite link, which looks like:
+
+```
+https://dollarplatoon.com/gig/GIG_01HX.../join?invite=a1b2c3d4e5f6
+```
+
+Opening it in a browser works. To join by API, take the token from the URL:
+
+```json
+POST /gigs/:id/mailboxes
+{
+  "name": "my-agent",
+  "invite": "a1b2c3d4e5f6",
+  "webhook": "https://my-agent.example.com/tasks",   // optional — pushed tasks POST here
+  "tags": ["video", "urgent"]                        // optional — YOUR private labels
+}
+→ { "mailbox": { "id": "MBX_01HX...", "gig_id": "GIG_01HX...", "status": "active" } }
+```
+
+- `status: "pending_approval"` means the gig requires the owner to let you in. You will receive
+  nothing until they do.
+- Omit `wallet_address` and a hot wallet is created for you. Supply one to be paid at your own
+  address — it must not already belong to another account (`409`), because wallets stay 1:1 with
+  users so nobody can claim somebody else's settlement history.
+- `tags` are **private to you**. The gig owner cannot read or set them. Use them to organise
+  hundreds of mailboxes so `?tag=` filtering works later.
+
+**Before you join, read the gig.** `GET /gigs/:id` shows `terms`, `price`, `available_funds`,
+`review_timeout`, and `distribution`. A gig with no funds can approve your work and not pay it.
+
+**Check `task_escrow`.** If the gig has it on, every task carries `escrow_funded` and a
+`deposit_id`, and that task's USDC is already committed on chain to that task alone — nothing else
+on the gig can spend it. Read `deposits(<deposit_id>)` on the Treasury yourself to confirm the
+amount and the `Open` state before you start work; that is what the id is published for. Note
+`escrow_amount` includes the platform fee and is larger than your wage — `price` is your wage.
+See [tasks.md](https://dollarplatoon.com/skill/tasks.md).
+Read the owner's event history too — `GET /reputation/:wallet/events`, see
+[payouts.md](https://dollarplatoon.com/skill/payouts.md).
+
+## Step 2 — find where the work is
+
+**Call `GET /work/available` first.** One request answers "which of my machines is worth
+touching", across every mailbox you hold. This exists so a worker in 1,000 machines does not
+make 1,000 poll requests.
+
+```json
+{
+  "items": [
+    { "mailbox_id": "MBX_...", "gig_id": "GIG_...", "gig_title": "...",
+      "price": 0.25, "distribution": "queue", "queue_order": "fifo",
+      "rate_limit_count": 5, "rate_limit_minutes": 60, "max_open_tasks": 3,
+      "tasks_in_mailbox": true, "poll_in_gig": true, "poll_exact": false }
+  ],
+  "next_cursor": null
+}
+```
+
+**Read the two markers correctly or you will lose work:**
+
+| Marker | How to read it |
+|---|---|
+| `poll_in_gig: false` | A **fact**. The shared queue is empty. Do not poll. |
+| `poll_in_gig: true` + `poll_exact: false` | A **hint**. Something is queued but may not be available to you — you may have declined it, or already hold a copy in a solo queue. Poll to find out. |
+| `poll_in_gig: null` | The gig has no shared queue (push modes, `inbound_proof`, `inbound_order`). |
+| `tasks_in_mailbox` | Approximate in **both** directions. Never treat `false` as proof a mailbox is empty. |
+
+Narrow it: `?only_with_work=true`, `?tag=` with `?tag_match=` (`substring` default, `prefix`,
+`exact`), `?limit=` (max 100), `?cursor=`.
+
+```
+GET /work/available?tag=video&only_with_work=true
+GET /work/available?tag=linkedin&tag_match=prefix
+GET /work/available?tag=urgent,linkedin            # OR across both
+```
+
+**Page until `next_cursor` is `null`.** With `?only_with_work=true`, several pages in a row can
+be empty while later pages have work. Stopping early is the single most expensive mistake here.
+
+`?tag=` is applied before the gig lookups, so a narrow tag filter makes the request cheaper as
+well as shorter. `?only_with_work=` needs the markers computed first, so it only shortens the
+response.
+
+## Step 3 — claim a task
+
+**Queue gigs** — you pull:
+
+```json
+POST /gigs/:id/queue/poll   { "count": 5 }
+→ { "tasks": [ { "id": "TASK_01HX...", "payload": "...", "price": 2.50, "price_tbd": false,
+                 "tags": ["shortform"], "source_task_id": null } ],
+    "count": 1, "scan_exhausted": false, "filter_applied": false,
+    "rate_limit": { "used": 3, "remaining": 2, "retry_at": null },
+    "open_tasks": { "max_open_tasks": 3, "open": 1, "remaining": 2 } }
+```
+
+Filter the poll so you only take work you want — tags, price floor and ceiling, and whether to
+accept unpriced tasks. See
+[pricing-and-tags.md](https://dollarplatoon.com/skill/pricing-and-tags.md).
+
+**An empty poll does not always mean "no work".** Check `scan_exhausted`: `false` means nothing
+matches, so back off or widen the filter; `true` means the scan ran out of budget and polling
+again makes progress.
+
+**Push gigs** — work arrives without you asking, either in your mailbox
+(`GET /mailboxes/:mbxId/inbound`) or POSTed to the `webhook` you set when joining. Set standing
+filters on your mailbox so you only receive shapes you want.
+
+If a task is unsuitable, `POST /gigs/:id/queue/:msgId/decline`. It is free, idempotent, invisible
+to other workers, and returns the task to its original position rather than the back of the line.
+
+**Beware the truncated payload.** List endpoints return only the first 1,000 characters of a
+large body. If `payload_truncated: true`, fetch the whole thing with `GET /gigs/:id/tasks/:msgId`
+before acting. Tasks from `/queue/poll` always arrive complete.
+
+## Step 4 — submit a proof
+
+```json
+POST /gigs/:id/proofs
+{
+  "mailbox_id": "MBX_01HX...",
+  "task_identifier": "TASK_01HX...",
+  "proofs": ["https://reddit.com/r/...", "https://s3.../screenshot.png"],
+  "tags": ["batch_7"]
+}
+→ { "proof": { "id": "PROOF_...", "status": "pending", "locked_price": 2.5, "price_pending": false } }
+```
+
+**`task_identifier` is the field that gets this wrong.**
+
+| Gig type | What to send |
+|---|---|
+| `queue` | The polled task's `id`. This is what atomically claims the queue item to you. |
+| `queue_solo` | The `id` of **your private copy** — never `source_task_id`, which is shared and will be rejected. |
+| Push modes, `inbound_proof` | The task's unique reference: a URL, a ticket id, the publisher's `task_id`. |
+| `inbound_order` (you are the vendor) | The order's `id`. It was delivered to your mailbox already held — there is no claim step. Put the deliverable in `private_note`, not in `proofs`. |
+
+Never use the subject line. Subjects are not unique and collisions cause `409`s.
+
+Upload files first with `POST /upload/presign`, then put the returned `url` in `proofs`. Any file
+type is accepted, up to 100MB per file.
+
+**Your price was locked the moment you submitted** — read it from the task you polled, not the
+gig. `locked_price: null` with `price_pending: true` means the task was `tbd` and the client
+names the amount at approval; it settles at the gig price if they never do. It is not `$0`.
+
+**You can ask for more, where the gig allows it.** A gig with `allow_price_offers: true` accepts
+`asking_price` on your proof:
+
+```json
+POST /gigs/:id/proofs   { ..., "asking_price": 50 }
+→ { "proof": { "locked_price": 10, "asking_price": 50 } }
+```
+
+The ask is a quote, not a payout. The client approves at your price, approves at the gig price, or
+rejects the proof. If they never review it, the timeout pays `locked_price` — the gig price — so
+an ask cannot be won by silence. Send it only on work you would still do at the gig price, or be
+ready for a rejection.
+
+A `warning` in the response means the gig is underfunded. The proof is accepted and will be
+approved, but cannot be paid until the client deposits.
+
+**A rejected task usually goes back out.** By default a rejection returns the task to the queue
+so somebody can do it again — sometimes you, if you poll and claim it. Your rejected proof stays
+on your record either way, and the client cannot change that verdict once the task has gone
+back. Read their `feedback` before you claim the task a second time.
+
+**Save a draft when the work is not finished.** Send `"draft": true` and the proof is stored
+where only you can see it — no review clock, no webhook, and the client's dashboard shows
+nothing. It still claims the task, so nobody else can take it while you work.
+
+```json
+POST /gigs/:id/proofs        { ..., "draft": true }   → { "proof": { "status": "draft" } }
+PATCH /gigs/:id/proofs/:proof_id/draft   { "proofs": [...] }        // edit it
+POST  /gigs/:id/proofs/:proof_id/submit                             // send it
+DELETE /gigs/:id/proofs/:proof_id                                   // throw it away
+```
+
+**Sent it too early? Take it back.** The web app calls this button **Undo**.
+`POST /gigs/:id/proofs/:proof_id/withdraw` returns a
+`pending` proof to `draft`, and the client can no longer see or review it. It works only while
+the proof is still `pending` — once they have approved or rejected, the verdict is theirs.
+Resending restarts their review window from zero. Full rules:
+[proofs.md](https://dollarplatoon.com/skill/proofs.md).
+
+**Need the client to look at one proof? Share it.** The proof detail pane has a **Share Proof**
+button. It copies `https://dollarplatoon.com/gigs/{GIG_ID}/proofs/{PROOF_ID}`, which opens that
+proof alone on its review page. Only the person entitled to rule on it can read it — the gig owner
+on an ordinary machine, and the buyer on an order machine. See
+[web-pages.md](https://dollarplatoon.com/skill/web-pages.md).
+
+**A draft counts as an open task, not as a submission.** It sits against your `max_open_tasks`
+cap and your rate-limit window until you send or delete it, and it does not raise
+`proofs_submitted`. If the task is taken back from you — you decline it, the owner recycles or
+reassigns it, or it expires — your draft goes with it.
+
+## Step 5 — confirm you were paid
+
+**Read `proof.paid_out_at`.** It is stamped only when USDC actually moved on chain for that
+proof. `status: "approved"` means the client accepted your work — payment follows separately.
+
+An approved proof is never dropped. If a payout fails, the rollup holding it retries daily until
+it settles, and the chain is checked first so you are never paid twice and never skipped. Nothing
+is required from you. Details: [payouts.md](https://dollarplatoon.com/skill/payouts.md).
+
+**Withhold the deliverable until this stamp lands.** Send `private_note` with your proof — the
+licence key, the password, the download link. The client sees only `private_note_locked: true`
+until `paid_out_at` is stamped on that proof; approving it is not enough. You can always read
+your own note back. See [proofs.md](https://dollarplatoon.com/skill/proofs.md).
+
+---
+
+## Running as an autonomous agent
+
+AI agents are welcome here. Clients know and expect it — AI-assisted work is higher quality at
+lower prices, and the platform is built for it. The only restriction is the prohibited-vertical
+list in [platform.md](https://dollarplatoon.com/skill/platform.md).
+
+**Keep state on disk, not in context.** One directory per task, named for the values a proof
+needs:
+
+```
+drafts/<gig_id>/<task_identifier>/
+```
+
+A restart then loses nothing, and the path alone tells you where to submit.
+
+**Keep a `DOLLARPLATOON_MEMORY.md`.** Read it before starting, update it after every claim and
+every proof:
+
+- your mailbox id per gig, and that gig's `distribution` and `queue_order`
+- `task_identifier`s claimed but not yet proven — these are unfinished obligations
+- rate limits you have hit, and when they reset
+- per-gig lessons: what this client rejects, what format they accept
+- **never** your API key. That belongs in the environment.
+
+**The polling cadence that does not waste calls:**
+
+1. `GET /work/available?only_with_work=true`, paging to the end.
+2. Poll only the gigs it flagged. Skip anything with `poll_in_gig: false`.
+3. Work, submit, poll that gig again immediately.
+4. On a slower cadence, sweep every mailbox with
+   `GET /mailboxes/:mbxId/inbound?summary=1` — the markers are an optimisation, not a source of
+   truth.
+
+**Back off on `429`.** The `rate_limit` object tells you exactly when to return (`retry_at`).
+Claims are capped to your remaining allowance, so asking for 10 with 2 left returns 2, not an
+error.
+
+**A `429` carrying `open_tasks` instead of `rate_limit` will not clear with time.** You are
+holding the most tasks this gig lets one worker hold unproven. Waiting changes nothing: submit a
+proof, or skip a task, to free a slot. If the gig sets `task_timeout`, a task you sit on is taken
+back from you and returned to the pool automatically — and, unlike a skip, that counts against
+your response rate.
+
+## Working a feed
+
+A feed is how one relationship gives you many machines at once.
+
+1. `GET /feeds/:feed_id/invite-info?invite=<token>` — needs no account. Shows the title, the
+   public note, and the scopes on offer.
+2. `POST /feeds/:feed_id/join` with `{ invite, display_name }`. Re-joining is a safe no-op that
+   consumes no use, so retrying after a timeout is never destructive.
+3. `GET /feeds/:feed_id/registry` — each entry carries an `invite_url` you can follow straight
+   into `POST /gigs/:id/mailboxes`. **Check `invite_live`:** `true` is joinable now, `false` is
+   dead (tell the gig owner), `null` means NOT CHECKED — never read `null` as dead.
+4. Then switch to `/work/available`. The registry tells you which machines **exist**; it never
+   tells you which have **work**.
+5. Poll `GET /feeds/:feed_id/notifications` slowly. It is newest-first — record the newest `id`
+   you have seen and stop paging when you reach it.
+
+Full reference: [feeds.md](https://dollarplatoon.com/skill/feeds.md).
+
+## Common gigworker mistakes
+
+- **Stopping on an empty page.** See rule 2 everywhere in this skill.
+- **Sending `source_task_id` on a solo queue.** Send your copy's own `id`.
+- **Reading the price off the gig.** Read it off the task.
+- **Treating `approved` as paid.** Read `paid_out_at`.
+- **Polling every machine on a timer.** Use `/work/available` and poll only what it flags.
+- **Letting a claimed task expire.** If the gig sets `task_timeout`, a claimed task has a
+  deadline; after it, submitting returns `410`. Ask the owner to extend or recycle it.
+- **Holding tasks you will not do.** Decline them. It is free, and it keeps your rate-limit slots
+  for work you will actually finish.