# agentx

Adopt this skill: https://proskills.md/skills/other/dezxbt-agentx

Page: https://proskills.md/skills/other/dezxbt-agentx
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 9959
sha: 73260f6970d6e8a67b49e3df4719637039909b3e
upstream: https://github.com/dezxbt/agentx/blob/HEAD/SKILL.md

````text
---
name: agentx
description: Drive X/Twitter from the CLI (read, post, DM, lists, communities, Grok, scheduling, analytics). Use when an agent needs to read or act on X/Twitter. Every command prints one JSON envelope.
---

# agentx — X/Twitter agent control surface

`agentx` is a single Go binary. Every command prints **one JSON envelope** to stdout, so parse stdout as JSON and check `.ok`. Build: `go build -o agentx ./cmd/agentx`.

## Envelope (always this shape)
```json
{"ok":true,"schema_version":"1","data":<any>,"pagination":{"nextCursor":"…"},"rateLimit":{…}}
{"ok":false,"schema_version":"1","error":{"code":"…","message":"…"}}
```
Rules: check `.ok` first. List data → `.data` is an array + `.pagination.nextCursor`. Single object → `.data` is an object. On error read `.error.code` (machine) + `.error.message` (human). Exit code ≠0 on error. Output is **compact single-line JSON by default** (token-efficient); add `--pretty` only when a human reads it.

## Setup (once)
```
agentx account add --name NAME --auth-token <auth_token> --ct0 <ct0>
```
Cookies come from a logged-in browser (`auth_token` + `ct0`). Env fallback: `TWITTER_AUTH_TOKEN`, `TWITTER_CT0`. Store: `$AGENTX_HOME/accounts.json` (default `~/.agentx`, mode 0600). Multi-account: add several, pick with `-a NAME`. `account login --name N --username U` (pass via `$TWITTER_PASSWORD`) does user/pass→cookies but X blocks login from datacenter IPs — prefer cookies.

## Global flags (may precede or follow the subcommand)
`-a NAME` account · `-n N` max items · `--cursor C` page cursor · `--pretty` human-readable JSON · `--account`/`--count` long forms.
IDs: any `<id>` also accepts a full tweet/list/community URL. Handles: with or without `@`.

## Commands (one line each)

READ
```
feed [--latest] [-n N] [--cursor C]      home timeline
search [--type Top|Latest] <query>       search
user <handle>  |  user --id <id>         profile
me                                       own profile
posts <handle> [-n N]                    a user's tweets
media <handle|id> [-n N]                 user's photos/videos
tweet <id>                               single tweet (zero-auth FxTwitter fallback)
thread <id>                              tweet + replies
article <id> [--markdown]                long-form X Article
analytics <id>                           metrics + engagement rate
likes <handle> | bookmarks | mentions    tweet lists
followers <handle> | following <handle>  user lists
retweeters <id> | likers <id>            who RT'd/liked (likers: author-only by X)
list <id> | list members <id>            List tweets / members
community posts <id> [--latest] | community info <id>
notifications [all|mentions|verified] | unread     (alias: notif)
trends [woeid] | trends locations        trending (Indonesia woeid=23424846)
scheduled | drafts                       your queued/draft tweets
settings                                 your privacy settings
```

WRITE (state-changing; reversible ones noted)
```
post <text> [--media f [--alt txt]] [--thread]    tweet (>280 → long-form, Premium)
reply <id> <text> [--media f] | quote <id> <text> [--media f]
poll <text> --option A --option B [--option C|D] [--duration MIN]
vote <id> <choice 1-4>
like/unlike  retweet/unretweet  bookmark/unbookmark  delete  <id>
pin/unpin <id>                                    pin tweet to profile
bookmark <id> --folder <id>                       bookmark into folder
follow/unfollow  mute/unmute  block/unblock  <handle>
edit <id> <text>                                  Premium
draft <text> | draft delete <id>
schedule <unix|+30m|+2h|+1d> <text> | unschedule <id>
profile [--name N] [--bio B] [--location L] [--url U]
avatar <img> | banner <img>
settings [--protected b] [--dms-from all|following] [--discoverable-email b] [--geo b]
topic follow|unfollow <topic_id>
list create <name> [--desc T] [--private] | list delete <id>
list add|remove <listid> <handle|id> | list subscribe|unsubscribe <id>
community join|leave <id> | community create <name>   (create is permanent)
bookmarks folder create <name> | delete <id>          (Premium)
dm send <handle> <text> [--media f]
```

GROK (AI)
```
grok <prompt>                            text answer (live web search built in)
grok image <prompt> [--out file]         generate image(s), download to file(s)
```

UTILITIES
```
download <id|url> [--out f] [--all]       save tweet media / a direct URL
watch <mentions|search <q>> [--interval 60s] [--once]   NDJSON stream of new tweets
account list|remove <n>|default [n]|check [n]
oauth inspect <authorize_url>             Sign-in-with-X: app name + scope audit (no approval)
oauth approve <authorize_url>             auto-approve consent → callback URL (see PERMISSION RULE)
oauth callback <callback_url>             GET the app callback to finish sign-in
```

## Pagination
List commands return `.pagination.nextCursor`. Pass it back via `--cursor` for the next page. `-n N` caps items in the response (note: the cursor still points past the full fetched page, so for exact paging use the cursor, not a tiny `-n`).

## Error codes (`.error.code`)
`not_authenticated` bad/expired cookies · `not_found` · `invalid_input` · `rate_limited` (see `.rateLimit`) · `query_id_error` X rotated a GraphQL id → set `AGENTX_QID_<Operation>=<id>` env or update constants · `network_error` · `api_error` x.com rejected (message has detail) · `account_error`.

## Gotchas
- **`oauth` PERMISSION RULE (Sign-in-with-X, agents MUST follow)** — `oauth approve` hands the account's permissions to a third-party app. Always run `oauth inspect` first and read `writeScopes` in the envelope: if it is NOT empty (`tweet.write`, `users.write`, `follows.write`, `dm.read/write`, `like.write`, `bookmark.write`) → **stop and get explicit confirmation from the human operator before approving.** Never approve account-control scopes on your own initiative — malicious developers deliberately bundle those permissions so the agent posts/follows/reads DMs on the user's behalf without the user realizing it (acting on the account unprompted = a violation). Scope `*.read` is safe; `offline.access` is reported in `persistentScopes` (refresh tokens, not a write) — OK to proceed. The inspect/approve envelope always carries a `permissionWarning` that flags this automatically.
- **TWO KINDS OF Sign-in-with-X SITES — diagnose first, don't retry blindly:**
  - **TYPE A — callback sets the session directly** (verified: fanszn/IPXExchange, Sovren):
    `GET redirect_uri` → the site sets its session cookie immediately → sign-in done.
    `agentx oauth callback` captures those cookies in `data.sessionCookies`;
    pass the site's state cookies via `--cookie name=value` (repeatable) if needed.
    Verify via the site's `me`/profile endpoint.
    **Working example: `examples/fanszn_connect_x.py`** — complete verified
    chain (start redirect -> approve -> callback with state cookie -> /me).
  - **TYPE B — session-bound callback** (verified: quest.dogeos.com):
    the site requires its own primary login first (DogeOS = SIWE wallet → jwt),
    then `POST .../social-connections/{provider}/initiate` (Bearer) →
    `sessionId` + `launchUrl` paired server-side. `agentx oauth approve
    <launchUrl>` still gets the code, but the callback must be executed WITH
    the site's session/state — otherwise: "Authentication failed" /
    `invalid_state` / still logged out despite a successful approve.
    **Fix: a thin site-specific tool** (~100 lines: site login → initiate →
    `agentx oauth approve` → GET the backend callback → poll async status
    `pending → connected`). Do not re-initiate while pending — it jams.
  - **Quick diagnosis:** approve succeeds and X issues a code, but the site
    stays logged out / errors → it is Type B; find the `initiate`/`confirm`
    endpoints in the site's JS bundle and stop retrying the callback.
  - **Working example: `examples/dogeos_connect_x.py`** — a complete,
    verified Type B connector (SIWE login → initiate → `agentx oauth approve`
    → GET backend callback → async poll). Copy it and swap the endpoints for
    your target site; the Gotchas in its docstring (field names, pending
    semantics, stuck-session cleanup) are the mistakes agents actually make.
- **Premium-gated** (work only on X Premium accounts; routing is correct, x.com returns a clear error otherwise): `edit`, note/long-form `post` (>280), `bookmarks folder` writes.
- **Account-eligibility**: `community create` needs an eligible account.
- **likers**: X returns the liker list only to the tweet's author; empty for others (retweeters is public).
- **grok image**: needs image-gen quota (free tier is limited/daily); errors clearly when the quota is spent.
- **DM**: only classic (unencrypted) DMs via `dm send/list/download`. X's new **XChat is end-to-end encrypted and out of scope** (keys are device-only, non-extractable).
- **Rate limit**: `.rateLimit` carries `x-rate-limit-*`; back off when `remaining` is low.
- `AGENTX_UTLS=1` sends a Chrome JA3 TLS fingerprint (HTTP/2) for stealth.
- Writes are real and public — confirm intent before posting/following/etc.

## Typical flows
- Read a user's latest: `agentx posts elonmusk -n 20`
- Reply: `agentx reply <id> "nice"` · Quote with image: `agentx quote <id> "look" --media pic.jpg`
- Thread: `agentx post --thread "long text…"` · Poll: `agentx poll "Q?" --option A --option B`
- Schedule: `agentx schedule +2h "later"` then `agentx scheduled`
- Ask Grok: `agentx grok "USD to IDR today?"` · Image: `agentx grok image "a dragon" --out d.png`
- Paginate: `agentx feed -n 40` → take `nextCursor` → `agentx feed --cursor <c>`
- Sign-in-with-X: `agentx oauth inspect <url>` (check permissionWarning) → `agentx oauth approve <url>` → GET/`oauth callback` on `data.redirect_uri` → verify the session via the target site's "me" endpoint
````

## File: README.md
size: 4930
sha: a975cb19645052e1ad4511bdc5ea6205bc67be64
upstream: https://github.com/dezxbt/agentx/blob/HEAD/README.md

````text
<div align="center">
  <img src="assets/logo.png" alt="AgentX" width="420">

  <h1>agentx</h1>
  <p><b>An agent-first X / Twitter client in Go.</b><br>
  One binary, one JSON envelope per command — so any agent runtime can drive X.</p>

  <p>
    <img alt="Go" src="https://img.shields.io/badge/Go-1.22%2B-00ADD8?logo=go&logoColor=white">
    <img alt="status" src="https://img.shields.io/badge/status-production-brightgreen">
    <img alt="interface" src="https://img.shields.io/badge/interface-JSON%20envelope-blue">
    <img alt="accounts" src="https://img.shields.io/badge/multi--account-yes-success">
  </p>
</div>

---

`agentx` is a from-scratch Go library **+** CLI built for **autonomous agents**. Every command prints a single predictable JSON object, supports **multiple accounts**, and keeps **`auth_token` cookies alive** by making traffic look like a real browser.

## ✨ Why cookies last longer here

X flags/expires `auth_token` cookies aggressively when traffic doesn't look human. agentx signs **every** authenticated request with:

- a freshly generated **`x-client-transaction-id`** — the exact algorithm x.com's web app runs (golden-tested),
- the **full browser header set** (bearer, `x-csrf-token`, `x-twitter-*`, `sec-fetch-*`, stable User-Agent),
- the complete cookie string,
- optional **uTLS** Chrome JA3 fingerprint over **HTTP/2** (`AGENTX_UTLS=1`).

## 🚀 Quick start

```bash
go build -o agentx ./cmd/agentx

# Register an account (cookies from a logged-in browser)
./agentx account add --name main --auth-token <auth_token> --ct0 <ct0>

# Read
./agentx feed -n 20
./agentx user jack
./agentx search --type Latest "golang" -n 20
./agentx analytics <tweet_id>

# Write
./agentx post "hello from agentx 👋"
./agentx reply <id> "nice!" --media pic.jpg
./agentx poll "Tabs or spaces?" --option Tabs --option Spaces

# Grok (AI)
./agentx grok "USD to IDR today?"
./agentx grok image "a majestic dragon" --out dragon.png
```

Every command prints **one JSON envelope**:

```json
{ "ok": true,  "schema_version": "1", "data": …, "pagination": {"nextCursor": "…"}, "rateLimit": {…} }
{ "ok": false, "schema_version": "1", "error": {"code": "…", "message": "…"} }
```

Check `.ok`, read `.data`, page with `.pagination.nextCursor`. Exit code is `0` on success, `1` on a handled error. Output is **compact single-line JSON by default** (token-efficient for agents) — add `--pretty` for human-readable output.

## 🧩 Features

| Area | What you get |
| --- | --- |
| **Read** | feed (for-you / following), search, user / posts / tweet / thread / **article**, media tab, bookmarks (+ folders), likes, followers / following, **lists** + members, **communities**, mentions, **notifications** + unread, **trends** (+ locations), **analytics** (engagement rate), retweeters / likers |
| **Write** | post, reply, quote, **polls** (+ vote), like / retweet / bookmark, follow / mute / block, **pin**, media upload (+ alt text), auto-**threads**, **scheduled** tweets, **drafts**, profile / avatar / banner / **settings**, **topics**, list & community management |
| **Grok** | text answers with **live web search**, and **image generation** (download to file) |
| **DM** | classic DM send / list / media / download |
| **Infra** | multi-account, zero-auth **FxTwitter** fallback, uTLS + HTTP/2, rate-limit surfacing, query-id override for X rotations, `watch` streaming, media `download` |

See **[SKILL.md](SKILL.md)** for the compact, token-efficient command reference and **[AGENTS.md](AGENTS.md)** for the full agent integration guide.

## 🏛️ Architecture

```
cmd/agentx              CLI — one JSON envelope per command
pkg/agent               High-level facade (account selection, client cache, fallbacks)
pkg/xclient             Authenticated x.com GraphQL/REST client (+ transaction signing)
pkg/transaction         x-client-transaction-id generator   [golden-tested]
pkg/account             Multi-account credential store (~/.agentx, 0600)   [tested]
pkg/backends/fxtwitter  Zero-auth single-tweet fallback
pkg/models              Backend-agnostic Tweet / UserProfile / Page
pkg/xerrors             Stable machine-readable error codes
```

## 🔌 Use as a Go library

```go
import "github.com/dezxbt/agentx/pkg/agent"

ag := agent.New(store)
page, err := ag.Feed(ctx, "main", false, 20, "")
```

## ⚠️ Notes

- **Premium-gated** (work on X Premium accounts; the client routes correctly and surfaces a clear error otherwise): long-form `post` (>280), `edit`, bookmark-folder writes.
- **likers** are returned by X only to the tweet's author (retweeters is public).
- **grok image** needs available image-generation quota.
- X's new **XChat is end-to-end encrypted and out of scope** — keys are device-only and non-extractable by design. Classic DMs work.
- Writes are **real and public** — confirm intent before acting.

## 📄 License

MIT — see [LICENSE](LICENSE).
````

## File: assets/logo.png
size: 866134
sha: 18373324cdb02739b6cfb862b125ae6286bf7351
upstream: https://github.com/dezxbt/agentx/blob/HEAD/assets/logo.png

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/assets/logo.png

## File: .gitignore
size: 179
sha: 24e319c4c94f3ace8ab9b16fe54420ab11554d00
upstream: https://github.com/dezxbt/agentx/blob/HEAD/.gitignore

```text
# Binaries
/agentx
*.exe
*.out

# Local agentx state (contains session secrets)
.agentx/
accounts.json

# Go
/vendor/
*.test
coverage.out

# Editor / OS
.DS_Store
.idea/
.vscode/
```

## File: AGENTS.md
size: 2819
sha: d21e5bcd1e95b859423e5108b4e917188827b4be
upstream: https://github.com/dezxbt/agentx/blob/HEAD/AGENTS.md

```text
# agentx — agent integration guide

This file tells an autonomous agent how to drive X/Twitter through agentx.

## Contract

- Drive everything through the `agentx` binary (or import `pkg/agent` in Go).
- Every command prints **one JSON object** to stdout and nothing else:
  - success: `{"ok":true,"schema_version":"1","data":...,"pagination":{"nextCursor":"..."}}`
  - failure: `{"ok":false,"schema_version":"1","error":{"code":"...","message":"..."}}`
  - process exit code is `0` on success, `1` on a handled error.
- Parse the envelope; never scrape human text. `data` shape depends on the
  command (a tweet array for timelines, a user object for `user`, etc.).

## Decision guide

| Goal | Command |
| --- | --- |
| Read my home feed | `agentx feed -n N` (add `--latest` for chronological) |
| Search | `agentx search --type Top\|Latest "<query>" -n N` |
| Look up a profile | `agentx user <handle>` |
| Read someone's tweets | `agentx posts <handle> -n N` |
| Read one tweet (no login needed) | `agentx tweet <id\|url>` |
| Read a tweet + replies | `agentx thread <id\|url>` |
| Publish | `agentx post "<text>"` |
| Reply / quote | `agentx reply <id> "<text>"` / `agentx quote <id> "<text>"` |
| Engage | `agentx like\|unlike\|retweet\|unretweet\|bookmark\|delete <id>` |

`<id|url>` accepts a numeric id or any `https://x.com/<user>/status/<id>` URL.

## Multi-account

- Register once: `agentx account add --name <n> --auth-token <t> --ct0 <c> [--cookie "<full cookie>"]`.
- Choose per call with `-a <name>` or set `AGENTX_ACCOUNT`.
- The first account becomes the default; change it with `agentx account default <name>`.
- Inspect with `agentx account list` (returns names + which is default).

Prefer supplying the **full browser cookie string** via `--cookie`: it keeps the
session looking like a real browser, which makes the cookies last much longer.

## Pagination

Timeline-style results include `pagination.nextCursor`. To page, re-issue the
same command with `--cursor <nextCursor>`. Stop when `nextCursor` is empty or
stops changing.

## Handling errors

Switch on `error.code`:

- `not_authenticated` → cookies missing/expired; ask the user to re-add the
  account, then retry.
- `rate_limited` → back off (seconds→minutes) and retry; the client already
  retries transient 429s a few times.
- `query_id_error` / repeated `not_found` on a known-good id → x.com rotated a
  GraphQL query id; report it so the operator can refresh ids.
- `invalid_input` → fix arguments; do not retry blindly.
- `network_error` → transient; retry with backoff.

## Notes for safe automation

- Writes (`post`, `like`, ...) change real account state. Confirm intent before
  bulk actions.
- Keep one stable User-Agent per account (set `--user-agent` at add time) — do
  not rotate it between requests.
```

## File: cmd/agentx/main.go
size: 57600
sha: 5c135918cc21d85ca267b8a3ffd1d413cdfc2859
upstream: https://github.com/dezxbt/agentx/blob/HEAD/cmd/agentx/main.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/cmd/agentx/main.go

## File: cmd/agentx/oauth.go
size: 6957
sha: 87c21d4f0942af80e68a6f3ad767950012909b37
upstream: https://github.com/dezxbt/agentx/blob/HEAD/cmd/agentx/oauth.go

```text
package main

import (
	"context"
	"os"
	"strings"

	"github.com/dezxbt/agentx/pkg/xclient"
	"github.com/dezxbt/agentx/pkg/xerrors"
)

// writeScopes are OAuth scopes that let an app ACT as the account (post,
// follow, DM, read DMs). Approving them hands over account control.
var writeScopes = map[string]string{
	"tweet.write":     "post/retweet/reply as the account",
	"users.write":     "follow/unfollow/mute/block as the account",
	"follows.write":   "follow/unfollow as the account",
	"dm.read":         "read the account's direct messages",
	"dm.write":        "send DMs as the account",
	"bookmark.write":  "modify bookmarks",
	"like.write":      "like/unlike as the account",
}

// persistentScopes keep access alive but cannot act — flagged separately
// from write scopes so read-only apps don't get a false account-control warn.
var persistentScopes = map[string]string{
	"offline.access": "stay connected until revoked (refresh tokens)",
}

// auditScopes splits the requested scopes into safe (read-only),
// account-control (write/DM), and persistent buckets.
func auditScopes(scopes []xclient.OAuthScopeInfo) (safe []string, dangerous map[string]string, persistent []string) {
	dangerous = map[string]string{}
	for _, s := range scopes {
		if reason, ok := writeScopes[s.Name]; ok {
			dangerous[s.Name] = reason
			continue
		}
		if _, ok := persistentScopes[s.Name]; ok {
			persistent = append(persistent, s.Name)
			continue
		}
		safe = append(safe, s.Name)
	}
	return safe, dangerous, persistent
}

// cmdOAuth handles `agentx oauth` — Sign-in-with-X via the account's session
// cookies, no browser needed:
//
//	agentx oauth inspect  <authorize_url>   show app name + scopes (no approval)
//	agentx oauth approve  <authorize_url>   auto-approve, print the callback URL
//	agentx oauth callback <callback_url>    GET the app callback (finishes sign-in)
//
// PERMISSION RULE: approve is a delegated account action. Before approving an
// app that requests ANY write scope, the operator (human) must explicitly
// confirm it — never approve account-control permissions on your own
// initiative. Read-only apps (users.read/tweet.read/follows.read) are safe to
// approve autonomously.
func cmdOAuth(ctx context.Context, args []string) {
	if len(args) == 0 {
		fail(xerrors.New(xerrors.InvalidInput, "usage: agentx oauth inspect|approve|callback <url>"))
	}
	sub, rest := args[0], args[1:]
	if len(rest) == 0 {
		fail(xerrors.New(xerrors.InvalidInput, "usage: agentx oauth %s <authorize_url>", sub))
	}
	targetURL := rest[0]

	var (
		rest3     []string
		authToken string
		ct0       string
	)
	switch sub {
	case "callback":
		// GET the app callback WITH a cookie jar: any Set-Cookie the app
		// issues on login (its own session) is captured and returned, so the
		// agent finishes sign-in without a browser. The jar only ever holds
		// the third-party app's cookies — it never sees X credentials.
		siteCookies, _ := flagValues(rest, "--cookie")
		res2, cbErr := runCallback(ctx, targetURL, siteCookies)
		if cbErr != nil {
			fail(cbErr)
		}
		emit(res2, nil)
		return
	case "inspect", "approve":
		// fall through to the shared path below
	default:
		fail(xerrors.New(xerrors.InvalidInput, "unknown oauth subcommand %q (inspect|approve|callback)", sub))
	}

	// approve/inspect need the cookies of an account. --auth-token/--ct0
	// overrides are supported for one-shot use without a stored account.
	var rest2 []string
	authToken, rest2 = flagValue(rest, "--auth-token")
	ct0, rest3 = flagValue(rest2, "--ct0")
	if authToken == "" {
		authToken = os.Getenv("TWITTER_AUTH_TOKEN")
	}
	if ct0 == "" {
		ct0 = os.Getenv("TWITTER_CT0")
	}

	var (
		res any
		err error
	)
	if authToken != "" && ct0 != "" {
		cl, cErr := oneShotClient(authToken, ct0)
		if cErr != nil {
			fail(cErr)
		}
		if sub == "inspect" {
			res, err = cl.OAuthAuthorize(ctx, targetURL)
		} else {
			res, err = cl.OAuthApprove(ctx, targetURL, false)
		}
	} else {
		if sub == "inspect" {
			res, err = newAgent().OAuthAuthorize(ctx, mustAccount(rest3), targetURL)
		} else {
			res, err = newAgent().OAuthApprove(ctx, mustAccount(rest3), targetURL, false)
		}
	}
	if err != nil {
		fail(err)
	}

	if consent, ok := res.(*xclient.OAuthConsent); ok {
		// inspect: report the app + scope audit, explicitly not approved
		safe, dangerous, persistent := auditScopes(consent.Scopes)
		emit(map[string]any{
			"app":         consent.AppName,
			"description": consent.AppDesc,
			"safeScopes":  safe,
			"writeScopes": dangerous,
			"persistentScopes": persistent,
			"permissionWarning": permissionWarning(dangerous),
			"approved":    false,
		}, nil)
		return
	}

	// approve: attach the same audit to the result so the caller sees what it
	// just consented to (and agents can log it).
	if appr, ok := res.(*xclient.OAuthApproval); ok {
		if appr.Consent != nil {
			safe, dangerous, persistent := auditScopes(appr.Consent.Scopes)
			emit(map[string]any{
				"redirect_uri":      appr.RedirectURI,
				"app":               appr.AppName,
				"safeScopes":        safe,
				"writeScopes":       dangerous,
				"persistentScopes":  persistent,
				"permissionWarning": permissionWarning(dangerous),
				"scopes":            appr.Scopes,
			}, nil)
			return
		}
	}
	emit(res, nil)
}

// permissionWarning renders the account-control warning shown on every
// inspect/approve that includes write scopes.
func permissionWarning(dangerous map[string]string) string {
	if len(dangerous) == 0 {
		return "read-only scopes — safe to approve"
	}
	names := make([]string, 0, len(dangerous))
	for k := range dangerous {
		names = append(names, k)
	}
	return "ACCOUNT-CONTROL SCOPES REQUESTED (" + strings.Join(names, ", ") + "): this app can act as the account. " +
		"Never approve without the human operator's explicit confirmation — malicious apps bundle these to post, follow, or read DMs on the user's behalf."
}

// truncateStr caps a string for envelope output.
func truncateStr(s string, n int) string {
	if len(s) <= n {
		return s
	}
	return s[:n]
}

// fetchCallback performs a plain GET against the app's callback URL. The
// response body is surfaced for debugging; the app sets its own session
// cookies in the browser normally, so this only proves the code was accepted.
func fetchCallback(ctx context.Context, rawURL string) (string, string, error) {
	if !strings.HasPrefix(rawURL, "http") {
		return "", "", xerrors.New(xerrors.InvalidInput, "callback url must be absolute")
	}
	req, err := newPlainGet(ctx, rawURL)
	if err != nil {
		return "", "", err
	}
	resp, err := plainHTTP.Do(req)
	if err != nil {
		return "", "", xerrors.New(xerrors.NetworkError, "callback fetch failed: %v", err)
	}
	defer resp.Body.Close()
	buf := make([]byte, 0, 4096)
	tmp := make([]byte, 2048)
	for {
		n, rerr := resp.Body.Read(tmp)
		buf = append(buf, tmp[:n]...)
		if rerr != nil || len(buf) > 64*1024 {
			break
		}
	}
	return rawURL, string(buf), nil
}
```

## File: cmd/agentx/oauth_callback.go
size: 2616
sha: 226f3bae7e7bfad104f424942ba8fa00bbc523ee
upstream: https://github.com/dezxbt/agentx/blob/HEAD/cmd/agentx/oauth_callback.go

```text
package main

import (
	"context"
	"net/http"
	"net/http/cookiejar"
	"net/url"
	"strings"
	"time"

	"github.com/dezxbt/agentx/pkg/xerrors"
)

// callbackJarHTTP performs the app-callback GET with a cookie jar so any
// Set-Cookie the app issues on login (its session) is captured and reported
// back to the caller. This is how sign-in-with-X finishes: the callback
// response carries the site's own session cookies.
type callbackResult struct {
	FinalURL  string            `json:"finalUrl"`
	Status    int               `json:"status"`
	SetCookie map[string]string `json:"sessionCookies"`
	Body      string            `json:"response"`
}

func runCallback(ctx context.Context, rawURL string, cookies []string) (*callbackResult, error) {
	if !strings.HasPrefix(rawURL, "http") {
		return nil, xerrors.New(xerrors.InvalidInput, "callback url must be absolute")
	}
	jar, jErr := cookiejar.New(nil)
	if jErr != nil {
		return nil, xerrors.Wrap(xerrors.NetworkError, jErr, "cookie jar")
	}
	// site-state cookies (e.g. fanszn_oauth={state,verifier}) must ride along
	// or the app rejects the callback with state_mismatch.
	baseURL, _ := url.Parse(rawURL)
	for _, kv := range cookies {
		k, v, ok := strings.Cut(kv, "=")
		if !ok || k == "" {
			return nil, xerrors.New(xerrors.InvalidInput, "bad --cookie %q (want name=value)", kv)
		}
		jar.SetCookies(baseURL, []*http.Cookie{{Name: k, Value: v}})
	}
	base, _ := url.Parse(rawURL)
	client := &http.Client{Timeout: 45 * time.Second, Jar: jar}
	req, rErr := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil)
	if rErr != nil {
		return nil, xerrors.Wrap(xerrors.InvalidInput, rErr, "bad callback url")
	}
	req.Header.Set("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/126.0 Safari/537.36")
	req.Header.Set("Accept", "*/*")
	resp, dErr := client.Do(req)
	if dErr != nil {
		return nil, xerrors.Wrap(xerrors.NetworkError, dErr, "callback fetch failed")
	}
	defer resp.Body.Close()
	buf := make([]byte, 0, 4096)
	tmp := make([]byte, 2048)
	for {
		n, rErr := resp.Body.Read(tmp)
		buf = append(buf, tmp[:n]...)
		if rErr != nil || len(buf) > 256*1024 {
			break
		}
	}
	out := &callbackResult{FinalURL: resp.Request.URL.String(), Status: resp.StatusCode, SetCookie: map[string]string{}, Body: string(buf)}
	// report cookies that now live in the jar for the app domain(s)
	for _, cURL := range []*url.URL{resp.Request.URL, base} {
		if cURL == nil {
			continue
		}
		for _, ck := range jar.Cookies(cURL) {
			if _, seen := out.SetCookie[ck.Name]; !seen {
				out.SetCookie[ck.Name] = ck.Value
			}
		}
	}
	return out, nil
}
```

## File: cmd/agentx/oauth_helper.go
size: 1100
sha: 7110c97a5662f183aa4390d4ade8ad00f57bd2da
upstream: https://github.com/dezxbt/agentx/blob/HEAD/cmd/agentx/oauth_helper.go

```text
package main

import (
	"context"
	"net/http"
	"time"

	"github.com/dezxbt/agentx/pkg/account"
	"github.com/dezxbt/agentx/pkg/xclient"
	"github.com/dezxbt/agentx/pkg/xerrors"
)

// oneShotClient builds a throwaway xclient from inline cookies (for
// `oauth approve --auth-token T --ct0 C` without a stored account).
func oneShotClient(authToken, ct0 string) (*xclient.Client, error) {
	acc := &account.Account{Name: "__oneshot__", AuthToken: authToken, CT0: ct0}
	return xclient.New(acc)
}

// plainHTTP is used only for `oauth callback` — a GET to the *third-party*
// app's callback URL. It never carries X credentials.
var plainHTTP = &http.Client{Timeout: 45 * time.Second}

func newPlainGet(ctx context.Context, rawURL string) (*http.Request, error) {
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil)
	if err != nil {
		return nil, xerrors.Wrap(xerrors.InvalidInput, err, "bad callback url")
	}
	req.Header.Set("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/126.0 Safari/537.36")
	req.Header.Set("Accept", "*/*")
	return req, nil
}
```

## File: examples/dogeos_connect_x.py
size: 7218
sha: 539cd06965b8027fb76ef0fdce4b8bd5b08f151e
upstream: https://github.com/dezxbt/agentx/blob/HEAD/examples/dogeos_connect_x.py

```text
#!/usr/bin/env python3
"""Reference implementation of a "Type B" Sign-in-with-X site connector.

Type B = the target site has its own primary login (here: SIWE wallet), and
the X OAuth callback is bound to a server-side session created by an
`initiate` endpoint. `agentx oauth approve` alone gets the X code but cannot
finish the login — you need this thin glue tool.

Generic flow (works for any Type B site, endpoints differ per site):

    1. PRIMARY LOGIN    get a bearer token from the site's own auth flow
    2. INITIATE         POST <site>/.../initiate  -> {sessionId, launchUrl}
    3. CONSENT          `agentx oauth approve <launchUrl>` -> callback URL w/ code
    4. CALLBACK         GET the callback (the site's backend validates it)
    5. POLL             GET the site's connection status until connected

The concrete endpoints below are from quest.dogeos.com (verified live) —
swap them for your target site's equivalents (find them in its JS bundle).
Requires: `agentx` >= v0.2.1 on PATH with an X account stored
(`agentx account add`), plus `requests` and `eth_account`.

Usage:
    export PRIVKEY=0x...                      # wallet private key
    python3 dogeos_connect_x.py status  --wallet 0x...
    python3 dogeos_connect_x.py connect --wallet 0x...
    python3 dogeos_connect_x.py connect --token <bearer jwt>   # skip step 1
"""
import argparse
import json
import os
import subprocess
import sys
import time

import requests

API = "https://quest-api.dogeos.com"  # DogeOS backend; replace per site
UA = ("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
      "Chrome/126.0 Safari/537.36")
PROVIDER = "twitter"  # site enum: twitter (NOT "x"), discord, telegram, ...

S = requests.Session()
S.headers.update({"User-Agent": UA, "Origin": "https://quest.dogeos.com",
                  "Referer": "https://quest.dogeos.com/",
                  "Content-Type": "application/json"})

def api(method, path, token=None, **kw):
    """Authenticated JSON request against the site backend."""
    headers = {"Authorization": f"Bearer {token}"} if token else {}
    r = S.request(method, API + path, headers=headers, timeout=45, **kw)
    try:
        return r.status_code, r.json()
    except Exception:
        return r.status_code, {"raw": r.text[:400]}

def site_login(address, private_key):
    """PRIMARY LOGIN (step 1) — SIWE wallet challenge/sign/session.

    Gotchas found by reversing the site's JS bundle:
      - the signed field is `signedMessage`, NOT `signature` (422 otherwise)
      - the token is `data.jwt`
    """
    from eth_account import Account
    from eth_account.messages import encode_defunct

    st, body = api("POST", "/v2/auth/wallet/challenges", json={"wallet": address})
    if st != 200:
        raise SystemExit(f"challenge failed: {st} {body}")
    d = body["data"]
    sig = Account.sign_message(encode_defunct(text=d["message"]),
                               private_key).signature.hex()
    if not sig.startswith("0x"):
        sig = "0x" + sig
    st, body = api("POST", "/v2/auth/wallet/sessions",
                   json={"wallet": address, "nonce": d["nonce"],
                         "signedMessage": sig})
    if st != 200:
        raise SystemExit(f"session failed: {st} {body}")
    tok = body["data"].get("jwt")
    if not tok:
        raise SystemExit(f"no jwt in response: {json.dumps(body)[:300]}")
    return tok

def connection_status(token):
    """Current state of the X connection on the site."""
    st, body = api("GET", "/v2/me/social-connections", token=token)
    conns = body.get("data", {}).get("connections", [])
    for c in conns:
        if c.get("provider") == PROVIDER:
            return c
    return {}

def connect(token, wait_secs=90):
    """Full Type B chain (steps 2-5)."""
    # A stuck `pending` session blocks a new initiate (launchUrl comes back
    # null until it expires) — clear it first if present.
    if connection_status(token).get("status") == "pending":
        api("DELETE", f"/v2/me/social-connections/{PROVIDER}", token=token)

    # 2) INITIATE — the server pairs sessionId with the X authorize state
    st, body = api("POST", f"/v2/me/social-connections/{PROVIDER}/initiate",
                   token=token,
                   json={"returnUrl": "https://quest.dogeos.com/oauth-callback"})
    if st != 200:
        raise SystemExit(f"initiate failed: {st} {json.dumps(body)[:300]}")
    launch = body.get("data", {}).get("launchUrl")
    if not launch:
        raise SystemExit(f"launchUrl null (stuck pending session?): {json.dumps(body)[:400]}")

    # 3) CONSENT — agentx approves X's consent screen, no browser needed
    r = subprocess.run(["agentx", "oauth", "approve", launch],
                       capture_output=True, text=True, timeout=120)
    env = json.loads(r.stdout)
    if not env.get("ok"):
        raise SystemExit(f"agentx approve failed: {env.get('error')}")
    callback = env["data"]["redirect_uri"].replace("&amp;", "&")
    print(f"[approve] scopes={env['data'].get('scopes')}")

    # 4) CALLBACK — the SITE'S BACKEND validates the state/code pair. Plain
    #    GET is enough; do NOT call the site's /confirm endpoint (DogeOS
    #    returns 400 confirm_not_supported — the backend does it itself).
    out = subprocess.run(["curl", "-s", "-L", "-A", UA, "-o", "/dev/null",
                          "-w", "%{http_code} %{url_effective}", callback],
                         capture_output=True, text=True, timeout=60)
    print(f"[callback] {out.stdout}")

    # 5) POLL — the backend resolves asynchronously (30-60s is normal).
    #    "pending" here is SUCCESS-IN-PROGRESS, not a failure: just keep
    #    polling, do not re-initiate.
    deadline = time.time() + wait_secs
    while time.time() < deadline:
        time.sleep(5)
        cur = connection_status(token)
        s = cur.get("status")
        if s == "connected":
            acct = (cur.get("account") or {}).get("username")
            print(f"[verify] {PROVIDER}: connected -> @{acct}")
            return cur
        if s != "pending":
            print(f"[verify] status={s} lastError={cur.get('lastError')}")
            return cur
    print("[verify] timeout — still pending")
    return connection_status(token)

def main():
    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    p.add_argument("cmd", choices=["status", "connect"])
    p.add_argument("--wallet", help="wallet address (0x..)")
    p.add_argument("--key", help="wallet private key hex, or env PRIVKEY")
    p.add_argument("--token", help="existing bearer token (skip primary login)")
    p.add_argument("--wait", type=int, default=90)
    a = p.parse_args()

    tok = a.token
    if not tok:
        key = a.key or os.environ.get("PRIVKEY")
        if not (a.wallet and key):
            raise SystemExit("need --wallet + --key (or env PRIVKEY), or --token")
        tok = site_login(a.wallet, key)
        print("[auth] site session OK")

    if a.cmd == "status":
        print(json.dumps(connection_status(tok), indent=2)[:1200])
        return

    if connect(tok, a.wait).get("status") != "connected":
        sys.exit(1)

if __name__ == "__main__":
    main()
```

## File: examples/fanszn_connect_x.py
size: 5240
sha: d15a704e4beaf9dae01c54b1d303b6512db9ce65
upstream: https://github.com/dezxbt/agentx/blob/HEAD/examples/fanszn_connect_x.py

```text
#!/usr/bin/env python3
"""Reference implementation of a "Type A" Sign-in-with-X site connector.

Type A = the site's OAuth callback sets its own session cookies directly on
GET. `agentx oauth approve` + `agentx oauth callback` finish the whole login —
no site login, no glue tool, just cookies from X.

Generic flow (endpoints differ per site; find them via the site's JS bundle):

    1. START        GET <site>/api/.../auth/x/start
                    -> 302 Location: x.com/i/oauth2/authorize?...  (the
                       authorize_url) AND a state cookie the callback must
                       echo back (e.g. fanszn_oauth={state,verifier})
    2. CONSENT      `agentx oauth approve <authorize_url>`
                    -> data.redirect_uri = the site's callback with the code
    3. CALLBACK     `agentx oauth callback <redirect_uri> --cookie <state jar>`
                    -> data.sessionCookies = the site's session
    4. VERIFY       GET the site's /me endpoint with the session cookie

Requires: `agentx` >= v0.2.1 on PATH with an X account stored
(`agentx account add`), plus `requests`.

Usage:
    python3 fanszn_connect_x.py            # full chain, verify /me
    python3 fanszn_connect_x.py --account NAME   # pick a stored X account
"""
import argparse
import json
import subprocess
import sys
from http.cookiejar import CookieJar

import requests

SITE = "https://fanszn.ipx.exchange"          # verified Type A site
START = "/api/fanszn/auth/x/start?returnTo=/fanszn/connect&ref=FAN-KQ4Z"
STATE_COOKIE = "fanszn_oauth"                  # site's state/verifier jar
ME_PATH = "/api/fanszn/me"                     # session verification endpoint

UA = ("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
      "Chrome/126.0 Safari/537.36")

def start(authorize_out):
    """START (step 1) — capture the authorize_url AND the state cookie.

    Gotcha: the state cookie returned by the start endpoint MUST ride along
    on the callback, or the site rejects it with `state_mismatch`. The jar
    value is already URL-encoded by the server — pass it through verbatim.
    """
    s = requests.Session()
    s.headers.update({"User-Agent": UA, "Cookie": "fanszn_ref=FAN-KQ4Z"})
    r = s.get(SITE + START, allow_redirects=False, timeout=45)
    if r.status_code not in (301, 302, 303, 307):
        raise SystemExit(f"start did not redirect: {r.status_code} {r.text[:200]}")
    authorize_out["authorize_url"] = r.headers["Location"]
    return s.cookies

def state_cookie_value(jar):
    for c in jar:
        if c.name == STATE_COOKIE:
            return c.value
    raise SystemExit(f"no {STATE_COOKIE} cookie from start endpoint")

def agentx_approve(authorize_url, account=None):
    """CONSENT (step 2) — approve X's consent screen via agentx."""
    cmd = ["agentx", "oauth", "approve", authorize_url]
    if account:
        cmd += ["-a", account]
    r = subprocess.run(cmd, capture_output=True, text=True, timeout=120)
    env = json.loads(r.stdout)
    if not env.get("ok"):
        raise SystemExit(f"agentx approve failed: {env.get('error')}")
    return env["data"]["redirect_uri"].replace("&amp;", "&")

def agentx_callback(callback_url, state_cookie, account=None):
    """CALLBACK (step 3) — GET the site callback WITH the state cookie.

    agentx runs the GET in a cookie jar and returns every Set-Cookie the
    site issues on login in `data.sessionCookies`. `--cookie` is repeatable.
    """
    cmd = ["agentx", "oauth", "callback", callback_url,
           "--cookie", f"{STATE_COOKIE}={state_cookie}"]
    if account:
        cmd += ["-a", account]
    r = subprocess.run(cmd, capture_output=True, text=True, timeout=120)
    env = json.loads(r.stdout)
    if not env.get("ok"):
        raise SystemExit(f"agentx callback failed: {env.get('error')}")
    return env["data"]

def main():
    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    p.add_argument("--account", help="stored agentx account (-a NAME)")
    authorize_out = {}
    p.set_defaults(func=lambda a: None)
    a = p.parse_args()

    # 1) START — authorize_url + state cookie in one redirect
    jar = start(authorize_out)
    state = state_cookie_value(jar)
    print(f"[start] authorize_url={authorize_out['authorize_url'][:80]}...")

    # 2) CONSENT
    callback = agentx_approve(authorize_out["authorize_url"], a.account)
    print("[approve] got redirect_uri")

    # 3) CALLBACK — capture the site session
    data = agentx_callback(callback, state, a.account)
    cookies = data["sessionCookies"]
    print(f"[callback] status={data['status']} final={data['finalUrl']}")
    print(f"[callback] sessionCookies: {sorted(cookies.keys())}")
    session = next((v for k, v in cookies.items() if "session" in k.lower()), None)
    if not session:
        raise SystemExit(f"no session cookie captured: {list(cookies.keys())}")

    # 4) VERIFY — prove the login actually landed
    me = requests.get(SITE + ME_PATH,
                      headers={"User-Agent": UA, "Cookie": f"{next(k for k in cookies if 'session' in k.lower())}={session}"},
                      timeout=45).json()
    print(f"[verify] me: {json.dumps(me)[:300]}")

if __name__ == "__main__":
    main()
```

## File: go.mod
size: 452
sha: e84beb3f9a4d6beedda0255b5152af70c30c4c51
upstream: https://github.com/dezxbt/agentx/blob/HEAD/go.mod

```text
module github.com/dezxbt/agentx

go 1.25.0

require (
	github.com/PuerkitoBio/goquery v1.12.0
	github.com/refraction-networking/utls v1.8.2
	golang.org/x/net v0.52.0
)

require (
	github.com/andybalholm/brotli v1.0.6 // indirect
	github.com/andybalholm/cascadia v1.3.3 // indirect
	github.com/klauspost/compress v1.17.4 // indirect
	golang.org/x/crypto v0.49.0 // indirect
	golang.org/x/sys v0.42.0 // indirect
	golang.org/x/text v0.35.0 // indirect
)
```

## File: go.sum
size: 7343
sha: 649182d014f7d042fdca83e3ac2def80f5e1ce6d
upstream: https://github.com/dezxbt/agentx/blob/HEAD/go.sum

```text
github.com/PuerkitoBio/goquery v1.12.0 h1:pAcL4g3WRXekcB9AU/y1mbKez2dbY2AajVhtkO8RIBo=
github.com/PuerkitoBio/goquery v1.12.0/go.mod h1:802ej+gV2y7bbIhOIoPY5sT183ZW0YFofScC4q/hIpQ=
github.com/andybalholm/brotli v1.0.6 h1:Yf9fFpf49Zrxb9NlQaluyE92/+X7UVHlhMNJN2sxfOI=
github.com/andybalholm/brotli v1.0.6/go.mod h1:fO7iG3H7G2nSZ7m0zPUDn85XEX2GTukHGRSepvi9Eig=
github.com/andybalholm/cascadia v1.3.3 h1:AG2YHrzJIm4BZ19iwJ/DAua6Btl3IwJX+VI4kktS1LM=
github.com/andybalholm/cascadia v1.3.3/go.mod h1:xNd9bqTn98Ln4DwST8/nG+H0yuB8Hmgu1YHNnWw0GeA=
github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
github.com/klauspost/compress v1.17.4 h1:Ej5ixsIri7BrIjBkRZLTo6ghwrEtHFk7ijlczPW4fZ4=
github.com/klauspost/compress v1.17.4/go.mod h1:/dCuZOvVtNoHsyb+cuJD3itjs3NbnF6KH9zAO4BDxPM=
github.com/refraction-networking/utls v1.8.2 h1:j4Q1gJj0xngdeH+Ox/qND11aEfhpgoEvV+S9iJ2IdQo=
github.com/refraction-networking/utls v1.8.2/go.mod h1:jkSOEkLqn+S/jtpEHPOsVv/4V4EVnelwbMQl4vCWXAM=
github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
golang.org/x/crypto v0.13.0/go.mod h1:y6Z2r+Rw4iayiXXAIxJIDAJ1zMW4yaTpebo8fPOliYc=
golang.org/x/crypto v0.19.0/go.mod h1:Iy9bg/ha4yyC70EfRS8jz+B6ybOBKMaSxLj6P6oBDfU=
golang.org/x/crypto v0.23.0/go.mod h1:CKFgDieR+mRhux2Lsu27y0fO304Db0wZe70UKqHu0v8=
golang.org/x/crypto v0.31.0/go.mod h1:kDsLvtWBEx7MV9tJOj9bnXsPbxwJQ6csT/x4KIN4Ssk=
golang.org/x/crypto v0.49.0 h1:+Ng2ULVvLHnJ/ZFEq4KdcDd/cfjrrjjNSXNzxg0Y4U4=
golang.org/x/crypto v0.49.0/go.mod h1:ErX4dUh2UM+CFYiXZRTcMpEcN8b/1gxEuv3nODoYtCA=
golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
golang.org/x/mod v0.12.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
golang.org/x/mod v0.15.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
golang.org/x/mod v0.17.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c=
golang.org/x/net v0.6.0/go.mod h1:2Tu9+aMcznHK/AK1HMvgo6xiTLG5rD5rZLDS+rp2Bjs=
golang.org/x/net v0.10.0/go.mod h1:0qNGK6F8kojg2nk9dLZ2mShWaEBan6FAoqfSigmmuDg=
golang.org/x/net v0.15.0/go.mod h1:idbUs1IY1+zTqbi8yxTbhexhEEk5ur9LInksu6HrEpk=
golang.org/x/net v0.21.0/go.mod h1:bIjVDfnllIU7BJ2DNgfnXvpSvtn8VRwhlsaeUTyUS44=
golang.org/x/net v0.25.0/go.mod h1:JkAGAh7GEvH74S6FOH42FLoXpXbE/aqXSrIQjXgsiwM=
golang.org/x/net v0.33.0/go.mod h1:HXLR5J+9DxmrqMwG9qjGCxZ+zKXxBru04zlTvWlWuN4=
golang.org/x/net v0.52.0 h1:He/TN1l0e4mmR3QqHMT2Xab3Aj3L9qjbhRm78/6jrW0=
golang.org/x/net v0.52.0/go.mod h1:R1MAz7uMZxVMualyPXb+VaqGSa3LIaUqk0eEt3w36Sw=
golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sync v0.1.0/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sync v0.3.0/go.mod h1:FU7BRWz2tNW+3quACPkgCx/L+uEAv1htQ0V83Z9Rj+Y=
golang.org/x/sync v0.6.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
golang.org/x/sync v0.7.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
golang.org/x/sync v0.10.0/go.mod h1:Czt+wKu1gCyEFDUtn0jG5QVvpJ6rzVqr5aXyt9drQfk=
golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.5.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.8.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.12.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
golang.org/x/sys v0.17.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
golang.org/x/sys v0.20.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
golang.org/x/sys v0.28.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
golang.org/x/sys v0.42.0 h1:omrd2nAlyT5ESRdCLYdm3+fMfNFE/+Rf4bDIQImRJeo=
golang.org/x/sys v0.42.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
golang.org/x/telemetry v0.0.0-20240228155512-f48c80bd79b2/go.mod h1:TeRTkGYfJXctD9OcfyVLyj2J3IxLnKwHJR8f4D8a3YE=
golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
golang.org/x/term v0.5.0/go.mod h1:jMB1sMXY+tzblOD4FWmEbocvup2/aLOaQEp7JmGp78k=
golang.org/x/term v0.8.0/go.mod h1:xPskH00ivmX89bAKVGSKKtLOWNx2+17Eiy94tnKShWo=
golang.org/x/term v0.12.0/go.mod h1:owVbMEjm3cBLCHdkQu9b1opXd4ETQWc3BhuQGKgXgvU=
golang.org/x/term v0.17.0/go.mod h1:lLRBjIVuehSbZlaOtGMbcMncT+aqLLLmKrsjNrUguwk=
golang.org/x/term v0.20.0/go.mod h1:8UkIAJTvZgivsXaD6/pH6U9ecQzZ45awqEOzuCvwpFY=
golang.org/x/term v0.27.0/go.mod h1:iMsnZpn0cago0GOrHO2+Y7u7JPn5AylBrcoWkElMTSM=
golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
golang.org/x/text v0.7.0/go.mod h1:mrYo+phRRbMaCq/xk9113O4dZlRixOauAjOtrjsXDZ8=
golang.org/x/text v0.9.0/go.mod h1:e1OnstbJyHTd6l/uOt8jFFHp6TRDWZR/bV3emEE/zU8=
golang.org/x/text v0.13.0/go.mod h1:TvPlkZtksWOMsz7fbANvkp4WM8x/WCo/om8BMLbz+aE=
golang.org/x/text v0.14.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
golang.org/x/text v0.15.0/go.mod h1:18ZOQIKpY8NJVqYksKHtTdi31H5itFRjB5/qKTNYzSU=
golang.org/x/text v0.21.0/go.mod h1:4IBbMaMmOPCJ8SecivzSH54+73PCFmPWxNTLm+vZkEQ=
golang.org/x/text v0.35.0 h1:JOVx6vVDFokkpaq1AEptVzLTpDe9KGpj5tR4/X+ybL8=
golang.org/x/text v0.35.0/go.mod h1:khi/HExzZJ2pGnjenulevKNX1W67CUy0AsXcNubPGCA=
golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU=
golang.org/x/tools v0.13.0/go.mod h1:HvlwmtVNQAhOuCjW7xxvovg8wbNq7LwfXh/k7wXUl58=
golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d/go.mod h1:aiJjzUbINMkxbQROHiO6hDPo2LHcIPhhQsa9DLh0yGk=
golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
```

## File: LICENSE
size: 1063
sha: d53d60568e73c88c883b54ef01ea2ca77750ab20
upstream: https://github.com/dezxbt/agentx/blob/HEAD/LICENSE

```text
MIT License

Copyright (c) 2026 DezXBT

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

## File: pkg/account/account.go
size: 2010
sha: 2b8dd9aff183a64608298a17203aba26ce704bbb
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/account/account.go

```text
// Package account manages multiple X/Twitter credential sets so a single agentx
// install can drive many accounts. Credentials are cookie-based (auth_token +
// ct0, plus an optional full cookie string for a richer browser fingerprint).
package account

import (
	"fmt"
	"strings"
	"time"
)

// Account holds one X session's credentials and metadata.
type Account struct {
	Name string `json:"name"`

	// AuthToken is the x.com `auth_token` cookie (the actual session secret).
	AuthToken string `json:"authToken"`
	// CT0 is the `ct0` cookie, also sent as the x-csrf-token header.
	CT0 string `json:"ct0"`
	// CookieString is the optional full Cookie header. When present it is sent
	// verbatim, preserving every cookie the browser had (best for longevity).
	CookieString string `json:"cookieString,omitempty"`

	// UserAgent pins the browser UA for this account. Keeping it stable across
	// requests is important for not tripping anti-automation heuristics.
	UserAgent string `json:"userAgent,omitempty"`
	// Proxy is an optional per-account proxy URL (http/https/socks5).
	Proxy string `json:"proxy,omitempty"`

	ScreenName string    `json:"screenName,omitempty"`
	AddedAt    time.Time `json:"addedAt"`
	LastUsed   time.Time `json:"lastUsed,omitempty"`
}

// Validate checks that the minimum required credentials are present.
func (a *Account) Validate() error {
	if strings.TrimSpace(a.Name) == "" {
		return fmt.Errorf("account name is required")
	}
	if strings.TrimSpace(a.AuthToken) == "" {
		return fmt.Errorf("account %q: auth_token is required", a.Name)
	}
	if strings.TrimSpace(a.CT0) == "" {
		return fmt.Errorf("account %q: ct0 is required", a.Name)
	}
	return nil
}

// Cookie returns the Cookie header value to send for this account. It uses the
// full cookie string when available, otherwise synthesises a minimal one.
func (a *Account) Cookie() string {
	if s := strings.TrimSpace(a.CookieString); s != "" {
		return s
	}
	return fmt.Sprintf("auth_token=%s; ct0=%s", a.AuthToken, a.CT0)
}
```

## File: pkg/account/store.go
size: 4536
sha: 53d0579223e677d84c34771fb7a42b7bd5cee5da
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/account/store.go

```text
package account

import (
	"encoding/json"
	"fmt"
	"os"
	"path/filepath"
	"sort"
	"sync"
	"time"

	"github.com/dezxbt/agentx/pkg/xerrors"
)

// Store is a thread-safe, file-backed collection of accounts.
type Store struct {
	path string

	mu       sync.RWMutex
	accounts map[string]*Account
	def      string // default account name
}

type persisted struct {
	Default  string     `json:"default"`
	Accounts []*Account `json:"accounts"`
}

// DefaultPath returns the standard store location (~/.agentx/accounts.json),
// overridable via the AGENTX_HOME environment variable.
func DefaultPath() string {
	if h := os.Getenv("AGENTX_HOME"); h != "" {
		return filepath.Join(h, "accounts.json")
	}
	home, err := os.UserHomeDir()
	if err != nil {
		return "accounts.json"
	}
	return filepath.Join(home, ".agentx", "accounts.json")
}

// Open loads the store at path, creating an empty one if it does not exist.
func Open(path string) (*Store, error) {
	if path == "" {
		path = DefaultPath()
	}
	s := &Store{path: path, accounts: map[string]*Account{}}
	data, err := os.ReadFile(path)
	if os.IsNotExist(err) {
		return s, nil
	}
	if err != nil {
		return nil, fmt.Errorf("account: read store: %w", err)
	}
	var p persisted
	if err := json.Unmarshal(data, &p); err != nil {
		return nil, fmt.Errorf("account: parse store: %w", err)
	}
	for _, a := range p.Accounts {
		s.accounts[a.Name] = a
	}
	s.def = p.Default
	return s, nil
}

func (s *Store) saveLocked() error {
	if err := os.MkdirAll(filepath.Dir(s.path), 0o700); err != nil {
		return fmt.Errorf("account: create store dir: %w", err)
	}
	p := persisted{Default: s.def}
	for _, a := range s.accounts {
		p.Accounts = append(p.Accounts, a)
	}
	sort.Slice(p.Accounts, func(i, j int) bool { return p.Accounts[i].Name < p.Accounts[j].Name })
	data, err := json.MarshalIndent(p, "", "  ")
	if err != nil {
		return err
	}
	// 0600: the file contains session secrets.
	if err := os.WriteFile(s.path, data, 0o600); err != nil {
		return fmt.Errorf("account: write store: %w", err)
	}
	return nil
}

// Add inserts or replaces an account and persists the store. The first account
// added becomes the default.
func (s *Store) Add(a *Account) error {
	if err := a.Validate(); err != nil {
		return err
	}
	s.mu.Lock()
	defer s.mu.Unlock()
	if a.AddedAt.IsZero() {
		a.AddedAt = time.Now()
	}
	s.accounts[a.Name] = a
	if s.def == "" {
		s.def = a.Name
	}
	return s.saveLocked()
}

// Remove deletes an account by name.
func (s *Store) Remove(name string) error {
	s.mu.Lock()
	defer s.mu.Unlock()
	if _, ok := s.accounts[name]; !ok {
		return fmt.Errorf("account %q not found", name)
	}
	delete(s.accounts, name)
	if s.def == name {
		s.def = ""
		for n := range s.accounts {
			s.def = n
			break
		}
	}
	return s.saveLocked()
}

// Get returns a copy of the named account.
func (s *Store) Get(name string) (*Account, error) {
	s.mu.RLock()
	defer s.mu.RUnlock()
	a, ok := s.accounts[name]
	if !ok {
		// account_error, not the api_error default: the documented code list maps
		// "the named account is not usable" to account_error, and agents switch on it.
		return nil, xerrors.New(xerrors.AccountError, "account %q not found", name)
	}
	cp := *a
	return &cp, nil
}

// Resolve returns the named account, or the default when name is empty.
func (s *Store) Resolve(name string) (*Account, error) {
	if name != "" {
		return s.Get(name)
	}
	s.mu.RLock()
	def := s.def
	s.mu.RUnlock()
	if def == "" {
		return nil, fmt.Errorf("no accounts configured; add one first")
	}
	return s.Get(def)
}

// List returns all accounts sorted by name.
func (s *Store) List() []*Account {
	s.mu.RLock()
	defer s.mu.RUnlock()
	out := make([]*Account, 0, len(s.accounts))
	for _, a := range s.accounts {
		cp := *a
		out = append(out, &cp)
	}
	sort.Slice(out, func(i, j int) bool { return out[i].Name < out[j].Name })
	return out
}

// Default returns the default account name (may be empty).
func (s *Store) Default() string {
	s.mu.RLock()
	defer s.mu.RUnlock()
	return s.def
}

// SetDefault changes the default account.
func (s *Store) SetDefault(name string) error {
	s.mu.Lock()
	defer s.mu.Unlock()
	if _, ok := s.accounts[name]; !ok {
		return fmt.Errorf("account %q not found", name)
	}
	s.def = name
	return s.saveLocked()
}

// Touch records that an account was just used.
func (s *Store) Touch(name, screenName string) {
	s.mu.Lock()
	defer s.mu.Unlock()
	if a, ok := s.accounts[name]; ok {
		a.LastUsed = time.Now()
		if screenName != "" {
			a.ScreenName = screenName
		}
		_ = s.saveLocked()
	}
}
```

## File: pkg/account/store_test.go
size: 1885
sha: 715cb87dcfabedfaad4c7d0015115dd59cb4e0d4
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/account/store_test.go

```text
package account

import (
	"path/filepath"
	"testing"
)

func TestStoreAddListResolvePersist(t *testing.T) {
	path := filepath.Join(t.TempDir(), "accounts.json")
	s, err := Open(path)
	if err != nil {
		t.Fatalf("open: %v", err)
	}

	if err := s.Add(&Account{Name: "a", AuthToken: "tok-a", CT0: "ct-a"}); err != nil {
		t.Fatalf("add a: %v", err)
	}
	if err := s.Add(&Account{Name: "b", AuthToken: "tok-b", CT0: "ct-b"}); err != nil {
		t.Fatalf("add b: %v", err)
	}

	if s.Default() != "a" {
		t.Errorf("default = %q, want a (first added)", s.Default())
	}
	if got := len(s.List()); got != 2 {
		t.Errorf("list len = %d, want 2", got)
	}

	// default resolution
	def, err := s.Resolve("")
	if err != nil || def.Name != "a" {
		t.Errorf("resolve default = %v, %v", def, err)
	}

	// reload from disk preserves state
	s2, err := Open(path)
	if err != nil {
		t.Fatalf("reopen: %v", err)
	}
	if s2.Default() != "a" || len(s2.List()) != 2 {
		t.Errorf("reload mismatch: default=%q len=%d", s2.Default(), len(s2.List()))
	}
	b, err := s2.Get("b")
	if err != nil || b.AuthToken != "tok-b" {
		t.Errorf("get b = %v, %v", b, err)
	}

	// remove default reassigns
	if err := s2.Remove("a"); err != nil {
		t.Fatalf("remove: %v", err)
	}
	if s2.Default() != "b" {
		t.Errorf("after remove default = %q, want b", s2.Default())
	}
}

func TestAccountValidateAndCookie(t *testing.T) {
	a := &Account{Name: "x", AuthToken: "tok", CT0: "csrf"}
	if err := a.Validate(); err != nil {
		t.Fatalf("validate: %v", err)
	}
	if got := a.Cookie(); got != "auth_token=tok; ct0=csrf" {
		t.Errorf("cookie = %q", got)
	}
	a.CookieString = "auth_token=tok; ct0=csrf; guest_id=v1"
	if a.Cookie() != a.CookieString {
		t.Error("expected full cookie string to be used verbatim")
	}

	bad := &Account{Name: "x"}
	if err := bad.Validate(); err == nil {
		t.Error("expected validation error for missing tokens")
	}
}
```

## File: pkg/agent/agent.go
size: 30358
sha: f5203ac5a21feacce95f122737a1267ba31d0226
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/agent/agent.go

```text
// Package agent is the high-level, agent-friendly facade over agentx. It hides
// account resolution, per-account client caching, the shared transaction
// provider, and zero-auth fallbacks behind a small, stable method set. This is
// the layer most agents should use.
package agent

import (
	"context"
	"net/http"
	"os"
	"strings"
	"sync"
	"time"

	"github.com/dezxbt/agentx/pkg/account"
	"github.com/dezxbt/agentx/pkg/backends/fxtwitter"
	"github.com/dezxbt/agentx/pkg/models"
	"github.com/dezxbt/agentx/pkg/transaction"
	"github.com/dezxbt/agentx/pkg/xclient"
)

// Agent coordinates accounts, clients and fallbacks. It is safe for concurrent
// use.
type Agent struct {
	store *account.Store
	tx    *transaction.Provider
	fx    *fxtwitter.Client

	mu      sync.Mutex
	clients map[string]*xclient.Client
}

// New builds an Agent over an account store. The transaction provider (which
// derives the x-client-transaction-id keys from x.com) is shared across all
// accounts because those keys are account-independent.
func New(store *account.Store) *Agent {
	hc := &http.Client{Timeout: 30 * time.Second}
	return &Agent{
		store:   store,
		tx:      transaction.NewProvider(transaction.WithHTTPClient(hc)),
		fx:      fxtwitter.New(hc),
		clients: map[string]*xclient.Client{},
	}
}

// Store exposes the underlying account store for management commands.
func (a *Agent) Store() *account.Store { return a.store }

// client resolves an account (empty => default) and returns a cached client.
func (a *Agent) client(name string) (*xclient.Client, error) {
	acc, err := a.store.Resolve(name)
	if err != nil {
		return nil, err
	}
	a.mu.Lock()
	defer a.mu.Unlock()
	if cl, ok := a.clients[acc.Name]; ok {
		return cl, nil
	}
	opts := []xclient.Option{xclient.WithTransactionProvider(a.tx)}
	if os.Getenv("AGENTX_UTLS") != "" {
		// opt-in Chrome-like TLS fingerprint for authenticated traffic
		opts = append(opts, xclient.WithUTLS())
	}
	cl, err := xclient.New(acc, opts...)
	if err != nil {
		return nil, err
	}
	a.clients[acc.Name] = cl
	return cl, nil
}

// hasAccounts reports whether any account is configured.
func (a *Agent) hasAccounts() bool { return a.store.Default() != "" }

// limitPage trims a page to at most count tweets when a positive count is
// requested. x.com ignores small count hints on timelines and returns a full
// page, so this enforces the caller's requested size. Note: the page cursor
// still points past the full fetched page, so paginating with a small count
// skips the untrimmed remainder.
func limitPage(p *models.Page, count int) *models.Page {
	if p != nil && count > 0 && len(p.Tweets) > count {
		p.Tweets = p.Tweets[:count]
	}
	return p
}

// Feed returns the home timeline for an account.
func (a *Agent) Feed(ctx context.Context, accountName string, latest bool, count int, cursor string) (*models.Page, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	p, err := cl.HomeTimeline(ctx, latest, count, cursor)
	if err != nil {
		return nil, err
	}
	return limitPage(p, count), nil
}

// Search runs an advanced search for an account.
func (a *Agent) Search(ctx context.Context, accountName, query, product string, count int, cursor string) (*models.Page, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	p, err := cl.Search(ctx, query, product, count, cursor)
	if err != nil {
		return nil, err
	}
	return limitPage(p, count), nil
}

// User resolves a profile. Requires an account.
func (a *Agent) User(ctx context.Context, accountName, screenName string) (*models.UserProfile, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	return cl.UserByScreenName(ctx, screenName)
}

// UserPosts fetches a user's tweets. Requires an account.
func (a *Agent) UserPosts(ctx context.Context, accountName, screenName string, count int, cursor string) (*models.Page, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	p, err := cl.UserPosts(ctx, screenName, count, cursor)
	if err != nil {
		return nil, err
	}
	return limitPage(p, count), nil
}

// Thread fetches a tweet plus its conversation. Requires an account.
func (a *Agent) Thread(ctx context.Context, accountName, tweetID string) (*models.Page, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	return cl.TweetDetail(ctx, tweetID)
}

// Bookmarks returns the authenticated user's bookmarks.
func (a *Agent) Bookmarks(ctx context.Context, accountName string, count int, cursor string) (*models.Page, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	p, err := cl.Bookmarks(ctx, count, cursor)
	if err != nil {
		return nil, err
	}
	return limitPage(p, count), nil
}

// Likes returns the tweets a user has liked.
func (a *Agent) Likes(ctx context.Context, accountName, screenName string, count int, cursor string) (*models.Page, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	p, err := cl.LikesByScreenName(ctx, screenName, count, cursor)
	if err != nil {
		return nil, err
	}
	return limitPage(p, count), nil
}

// ListTweets returns the latest tweets of a List.
func (a *Agent) ListTweets(ctx context.Context, accountName, listID string, count int, cursor string) (*models.Page, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	p, err := cl.ListTweets(ctx, listID, count, cursor)
	if err != nil {
		return nil, err
	}
	return limitPage(p, count), nil
}

// CommunityTweets returns the timeline of posts in a Community.
func (a *Agent) CommunityTweets(ctx context.Context, accountName, communityID string, count int, cursor string, latest bool) (*models.Page, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	p, err := cl.CommunityTweets(ctx, communityID, count, cursor, latest)
	if err != nil {
		return nil, err
	}
	return limitPage(p, count), nil
}

// CommunityInfo returns metadata about a Community.
func (a *Agent) CommunityInfo(ctx context.Context, accountName, communityID string) (map[string]any, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	return cl.CommunityInfo(ctx, communityID)
}

// JoinCommunity / LeaveCommunity move the authenticated account in/out of a Community.
func (a *Agent) JoinCommunity(ctx context.Context, accountName, communityID string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.JoinCommunity(ctx, communityID) })
}

func (a *Agent) LeaveCommunity(ctx context.Context, accountName, communityID string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.LeaveCommunity(ctx, communityID) })
}

// CreateCommunity creates a new Community (permanent, not undoable here).
func (a *Agent) CreateCommunity(ctx context.Context, accountName, name string) (map[string]any, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	return cl.CreateCommunity(ctx, name)
}

// ListMembers returns the members of a List.
func (a *Agent) ListMembers(ctx context.Context, accountName, listID string, count int, cursor string) (*models.UserPage, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	p, err := cl.ListMembers(ctx, listID, count, cursor)
	if err != nil {
		return nil, err
	}
	return limitUserPage(p, count), nil
}

// CreateList creates a List owned by the authenticated account.
func (a *Agent) CreateList(ctx context.Context, accountName, name, description string, private bool) (map[string]any, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	return cl.CreateList(ctx, name, description, private)
}

// DeleteList deletes a List owned by the authenticated account.
func (a *Agent) DeleteList(ctx context.Context, accountName, listID string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.DeleteList(ctx, listID) })
}

// SubscribeList / UnsubscribeList follow or unfollow a List owned by anyone.
func (a *Agent) SubscribeList(ctx context.Context, accountName, listID string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.SubscribeList(ctx, listID) })
}

func (a *Agent) UnsubscribeList(ctx context.Context, accountName, listID string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.UnsubscribeList(ctx, listID) })
}

// UserByID resolves a profile by numeric user id.
func (a *Agent) UserByID(ctx context.Context, accountName, userID string) (*models.UserProfile, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	return cl.UserByRestId(ctx, userID)
}

// UserMedia returns a user's media tab. The target may be a @handle or numeric id.
func (a *Agent) UserMedia(ctx context.Context, accountName, target string, count int, cursor string) (*models.Page, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	userID, err := a.resolveUserID(ctx, cl, target)
	if err != nil {
		return nil, err
	}
	p, err := cl.UserMedia(ctx, userID, count, cursor)
	if err != nil {
		return nil, err
	}
	return limitPage(p, count), nil
}

// Trends returns trending topics for a WOEID location (empty = worldwide).
func (a *Agent) Trends(ctx context.Context, accountName, woeid string) ([]xclient.Trend, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	return cl.Trends(ctx, woeid)
}

// PinTweet / UnpinTweet manage the account's pinned profile tweet.
func (a *Agent) PinTweet(ctx context.Context, accountName, tweetID string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.PinTweet(ctx, tweetID) })
}

func (a *Agent) UnpinTweet(ctx context.Context, accountName, tweetID string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.UnpinTweet(ctx, tweetID) })
}

// AddListMember / RemoveListMember edit a List's membership. The member may be a
// @handle or numeric id.
func (a *Agent) AddListMember(ctx context.Context, accountName, listID, member string) error {
	return a.listMember(ctx, accountName, listID, member, true)
}

func (a *Agent) RemoveListMember(ctx context.Context, accountName, listID, member string) error {
	return a.listMember(ctx, accountName, listID, member, false)
}

func (a *Agent) listMember(ctx context.Context, accountName, listID, member string, add bool) error {
	cl, err := a.client(accountName)
	if err != nil {
		return err
	}
	userID, err := a.resolveUserID(ctx, cl, member)
	if err != nil {
		return err
	}
	if add {
		return cl.AddListMember(ctx, listID, userID)
	}
	return cl.RemoveListMember(ctx, listID, userID)
}

// isNumericID reports whether s is a non-empty all-digit string (a user id).
func isNumericID(s string) bool {
	if s == "" {
		return false
	}
	for _, r := range s {
		if r < '0' || r > '9' {
			return false
		}
	}
	return true
}

// resolveUserID returns target unchanged if it is already a numeric id,
// otherwise resolves the @handle via UserByScreenName.
func (a *Agent) resolveUserID(ctx context.Context, cl *xclient.Client, target string) (string, error) {
	target = strings.TrimPrefix(target, "@")
	if isNumericID(target) {
		return target, nil
	}
	u, err := cl.UserByScreenName(ctx, target)
	if err != nil {
		return "", err
	}
	return u.ID, nil
}

// BookmarkFolders lists the account's bookmark folders.
func (a *Agent) BookmarkFolders(ctx context.Context, accountName string) ([]xclient.BookmarkFolder, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	return cl.BookmarkFolders(ctx)
}

// BookmarkFolderTweets returns the tweets in a bookmark folder.
func (a *Agent) BookmarkFolderTweets(ctx context.Context, accountName, folderID string, count int, cursor string) (*models.Page, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	p, err := cl.BookmarkFolderTweets(ctx, folderID, count, cursor)
	if err != nil {
		return nil, err
	}
	return limitPage(p, count), nil
}

// CreateBookmarkFolder creates a bookmark folder.
func (a *Agent) CreateBookmarkFolder(ctx context.Context, accountName, name string) (*xclient.BookmarkFolder, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	return cl.CreateBookmarkFolder(ctx, name)
}

// DeleteBookmarkFolder deletes a bookmark folder.
func (a *Agent) DeleteBookmarkFolder(ctx context.Context, accountName, folderID string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.DeleteBookmarkFolder(ctx, folderID) })
}

// BookmarkToFolder bookmarks a tweet into a specific folder.
func (a *Agent) BookmarkToFolder(ctx context.Context, accountName, tweetID, folderID string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.BookmarkToFolder(ctx, tweetID, folderID) })
}

// Retweeters / Favoriters return the accounts that retweeted or liked a tweet.
func (a *Agent) Retweeters(ctx context.Context, accountName, tweetID string, count int, cursor string) (*models.UserPage, error) {
	return a.engagers(ctx, accountName, tweetID, count, cursor, true)
}

func (a *Agent) Favoriters(ctx context.Context, accountName, tweetID string, count int, cursor string) (*models.UserPage, error) {
	return a.engagers(ctx, accountName, tweetID, count, cursor, false)
}

func (a *Agent) engagers(ctx context.Context, accountName, tweetID string, count int, cursor string, rt bool) (*models.UserPage, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	var p *models.UserPage
	if rt {
		p, err = cl.Retweeters(ctx, tweetID, count, cursor)
	} else {
		p, err = cl.Favoriters(ctx, tweetID, count, cursor)
	}
	if err != nil {
		return nil, err
	}
	return limitUserPage(p, count), nil
}

// ScheduleTweet queues a tweet for executeAt (unix seconds).
func (a *Agent) ScheduleTweet(ctx context.Context, accountName, text string, executeAt int64) (string, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return "", err
	}
	return cl.ScheduleTweet(ctx, text, executeAt, nil)
}

// ScheduledTweets lists pending scheduled tweets.
func (a *Agent) ScheduledTweets(ctx context.Context, accountName string) ([]xclient.ScheduledTweet, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	return cl.ScheduledTweets(ctx)
}

// DeleteScheduledTweet removes a pending scheduled tweet.
func (a *Agent) DeleteScheduledTweet(ctx context.Context, accountName, id string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.DeleteScheduledTweet(ctx, id) })
}

// Badges returns the account's unread counts.
func (a *Agent) Badges(ctx context.Context, accountName string) (*xclient.BadgeCount, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	return cl.Badges(ctx)
}

// Notifications returns the authenticated account's notifications timeline.
func (a *Agent) Notifications(ctx context.Context, accountName, tab string, count int, cursor string) (*xclient.NotificationPage, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	p, err := cl.Notifications(ctx, tab, count, cursor)
	if err != nil {
		return nil, err
	}
	if count > 0 && len(p.Items) > count {
		p.Items = p.Items[:count]
	}
	return p, nil
}

// Followers / Following return a user's social graph.
func (a *Agent) Followers(ctx context.Context, accountName, screenName string, count int, cursor string) (*models.UserPage, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	p, err := cl.FollowersByScreenName(ctx, screenName, count, cursor)
	if err != nil {
		return nil, err
	}
	return limitUserPage(p, count), nil
}

func (a *Agent) Following(ctx context.Context, accountName, screenName string, count int, cursor string) (*models.UserPage, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	p, err := cl.FollowingByScreenName(ctx, screenName, count, cursor)
	if err != nil {
		return nil, err
	}
	return limitUserPage(p, count), nil
}

func limitUserPage(p *models.UserPage, count int) *models.UserPage {
	if p != nil && count > 0 && len(p.Users) > count {
		p.Users = p.Users[:count]
	}
	return p
}

// Tweet fetches a single tweet. With an account it uses the authenticated API;
// without one it transparently falls back to the zero-auth FxTwitter backend.
func (a *Agent) Tweet(ctx context.Context, accountName, tweetID string) (*models.Tweet, error) {
	// An explicitly requested account that cannot be resolved must fail loudly:
	// falling through to the unauthenticated FxTwitter path would otherwise look
	// like success for an account name that does not exist.
	var accountErr error
	if a.hasAccounts() || accountName != "" {
		cl, err := a.client(accountName)
		if err != nil {
			accountErr = err
		} else if page, derr := cl.TweetDetail(ctx, tweetID); derr == nil {
			for i := range page.Tweets {
				if page.Tweets[i].ID == tweetID {
					return &page.Tweets[i], nil
				}
			}
			if len(page.Tweets) > 0 {
				return &page.Tweets[0], nil
			}
		}
	}
	if accountName != "" && accountErr != nil {
		return nil, accountErr
	}
	return a.fx.GetTweet(ctx, tweetID)
}

// TweetAnalytics is a tweet's engagement metrics plus a derived engagement rate.
type TweetAnalytics struct {
	ID             string         `json:"id"`
	Text           string         `json:"text,omitempty"`
	Author         string         `json:"author,omitempty"`
	Metrics        models.Metrics `json:"metrics"`
	Engagements    int            `json:"engagements"`       // likes+RTs+replies+quotes+bookmarks
	EngagementRate float64        `json:"engagementRatePct"` // engagements / views, percent
}

// Analytics fetches a tweet and reports its metrics with a computed engagement
// rate. X does not expose its private analytics (link clicks, profile visits)
// through a public API op, so this surfaces the full set of available counts
// (views/impressions, likes, retweets, replies, quotes, bookmarks).
func (a *Agent) Analytics(ctx context.Context, accountName, tweetID string) (*TweetAnalytics, error) {
	t, err := a.Tweet(ctx, accountName, tweetID)
	if err != nil {
		return nil, err
	}
	m := t.Metrics
	eng := m.Likes + m.Retweets + m.Replies + m.Quotes + m.Bookmarks
	rate := 0.0
	if m.Views > 0 {
		rate = float64(eng) / float64(m.Views) * 100
	}
	return &TweetAnalytics{
		ID: t.ID, Text: t.Text, Author: t.Author.ScreenName,
		Metrics: m, Engagements: eng, EngagementRate: rate,
	}, nil
}

// Article fetches a single tweet by id and populates the X Article fields when
// the tweet is a long-form article. The article endpoint is authenticated, so
// an account is required (no zero-auth fallback). markdown renders the article
// body as markdown instead of plain text.
func (a *Agent) Article(ctx context.Context, accountName, tweetID string, markdown bool) (*models.Tweet, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	return cl.Article(ctx, tweetID, markdown)
}

// Mentions returns tweets mentioning the authenticated user. cursor is the v1.1
// max_id for older pages.
func (a *Agent) Mentions(ctx context.Context, accountName string, count int, cursor string) (*models.Page, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	p, err := cl.Mentions(ctx, count, cursor)
	if err != nil {
		return nil, err
	}
	return limitPage(p, count), nil
}

// SendDM sends a direct message to a @handle (resolved to a user id first).
func (a *Agent) SendDM(ctx context.Context, accountName, screenName, text string) error {
	cl, err := a.client(accountName)
	if err != nil {
		return err
	}
	u, err := cl.UserByScreenName(ctx, screenName)
	if err != nil {
		return err
	}
	return cl.SendDM(ctx, u.ID, text)
}

// SendDMMedia sends a media DM to a @handle.
func (a *Agent) SendDMMedia(ctx context.Context, accountName, screenName, text string, data []byte, mimeType string) error {
	cl, err := a.client(accountName)
	if err != nil {
		return err
	}
	u, err := cl.UserByScreenName(ctx, screenName)
	if err != nil {
		return err
	}
	return cl.SendDMMedia(ctx, u.ID, text, data, mimeType)
}

// SetAltText sets accessibility alt text on an uploaded media id.
func (a *Agent) SetAltText(ctx context.Context, accountName, mediaID, text string) error {
	cl, err := a.client(accountName)
	if err != nil {
		return err
	}
	return cl.SetAltText(ctx, mediaID, text)
}

// DirectMessages lists recent DMs for an account.
func (a *Agent) DirectMessages(ctx context.Context, accountName string, count int) ([]xclient.DirectMessage, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	return cl.DirectMessages(ctx, count)
}

// DownloadMedia fetches the bytes of an auth-gated media URL for an account.
func (a *Agent) DownloadMedia(ctx context.Context, accountName, url string) ([]byte, string, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, "", err
	}
	return cl.DownloadMedia(ctx, url)
}

// PostThread posts a sequence of tweets as a self-reply chain (the first is a
// root tweet, each subsequent one replies to the previous) and returns them.
func (a *Agent) PostThread(ctx context.Context, accountName string, chunks []string, firstMedia []string) ([]models.Tweet, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	var out []models.Tweet
	replyTo := ""
	for i, c := range chunks {
		opts := xclient.PostOptions{ReplyToID: replyTo}
		if i == 0 {
			opts.MediaIDs = firstMedia
		}
		t, err := cl.Post(ctx, c, opts)
		if err != nil {
			return out, err
		}
		out = append(out, *t)
		replyTo = t.ID
	}
	if len(out) > 0 {
		a.store.Touch(cl.Account().Name, out[0].Author.ScreenName)
	}
	return out, nil
}

// Check verifies an account's cookies are still valid by resolving its own
// profile, returning that profile on success.
func (a *Agent) Check(ctx context.Context, accountName string) (*models.UserProfile, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	return cl.Me(ctx)
}

// Me returns the authenticated user's own profile for an account.
func (a *Agent) Me(ctx context.Context, accountName string) (*models.UserProfile, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	u, err := cl.Me(ctx)
	if err == nil && u != nil {
		a.store.Touch(cl.Account().Name, u.ScreenName)
	}
	return u, err
}

// Follow / Unfollow / Mute / Unmute / Block / Unblock act on a @handle.
func (a *Agent) Follow(ctx context.Context, accountName, screenName string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.Follow(ctx, screenName) })
}
func (a *Agent) Unfollow(ctx context.Context, accountName, screenName string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.Unfollow(ctx, screenName) })
}
func (a *Agent) Mute(ctx context.Context, accountName, screenName string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.Mute(ctx, screenName) })
}
func (a *Agent) Unmute(ctx context.Context, accountName, screenName string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.Unmute(ctx, screenName) })
}
func (a *Agent) Block(ctx context.Context, accountName, screenName string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.Block(ctx, screenName) })
}
func (a *Agent) Unblock(ctx context.Context, accountName, screenName string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.Unblock(ctx, screenName) })
}

// Post creates a tweet/reply/quote for an account.
func (a *Agent) Post(ctx context.Context, accountName, text string, opts xclient.PostOptions) (*models.Tweet, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	t, err := cl.Post(ctx, text, opts)
	if err == nil {
		a.store.Touch(cl.Account().Name, t.Author.ScreenName)
	}
	return t, err
}

// EditTweet replaces the text of an existing tweet (Premium-gated).
func (a *Agent) EditTweet(ctx context.Context, accountName, tweetID, text string) (*models.Tweet, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	return cl.Post(ctx, text, xclient.PostOptions{EditTweetID: tweetID})
}

// CreateDraft saves a draft tweet and returns its id.
func (a *Agent) CreateDraft(ctx context.Context, accountName, text string) (string, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return "", err
	}
	return cl.CreateDraft(ctx, text, nil)
}

// Drafts lists the account's saved drafts.
func (a *Agent) Drafts(ctx context.Context, accountName string) ([]xclient.Draft, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	return cl.Drafts(ctx)
}

// DeleteDraft removes a draft tweet.
func (a *Agent) DeleteDraft(ctx context.Context, accountName, draftID string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.DeleteDraft(ctx, draftID) })
}

// GrokAsk sends a prompt to Grok and returns the reply.
func (a *Agent) GrokAsk(ctx context.Context, accountName, prompt string) (string, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return "", err
	}
	return cl.GrokAsk(ctx, prompt)
}

// GrokImage asks Grok to generate an image and returns the attachment URLs.
func (a *Agent) GrokImage(ctx context.Context, accountName, prompt string) ([]string, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	return cl.GrokImage(ctx, prompt)
}

// VotePoll votes choice (1..N) on the poll attached to a tweet.
func (a *Agent) VotePoll(ctx context.Context, accountName, tweetID string, choice int) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.VotePoll(ctx, tweetID, choice) })
}

// UpdateProfile edits the account's profile (name, bio, location, url).
func (a *Agent) UpdateProfile(ctx context.Context, accountName string, f xclient.ProfileFields) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.UpdateProfile(ctx, f) })
}

// Settings returns the account's privacy/DM/discovery settings.
func (a *Agent) Settings(ctx context.Context, accountName string) (map[string]any, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	return cl.Settings(ctx)
}

// UpdateSettings changes account settings (only the provided keys).
func (a *Agent) UpdateSettings(ctx context.Context, accountName string, fields map[string]string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.UpdateSettings(ctx, fields) })
}

// UpdateAvatar / UpdateBanner set the profile picture / banner from image bytes.
func (a *Agent) UpdateAvatar(ctx context.Context, accountName string, image []byte) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.UpdateAvatar(ctx, image) })
}

func (a *Agent) UpdateBanner(ctx context.Context, accountName string, image []byte) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.UpdateBanner(ctx, image) })
}

// FollowTopic / UnfollowTopic manage followed Topics.
func (a *Agent) FollowTopic(ctx context.Context, accountName, topicID string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.FollowTopic(ctx, topicID) })
}

func (a *Agent) UnfollowTopic(ctx context.Context, accountName, topicID string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.UnfollowTopic(ctx, topicID) })
}

// TrendLocations lists places (WOEIDs) with trending data.
func (a *Agent) TrendLocations(ctx context.Context, accountName string) ([]xclient.TrendLocation, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	return cl.TrendLocations(ctx)
}

// PostPoll posts a tweet with an attached poll (2–4 choices, duration minutes).
func (a *Agent) PostPoll(ctx context.Context, accountName, text string, choices []string, durationMinutes int) (*models.Tweet, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	return cl.PostPoll(ctx, text, choices, durationMinutes)
}

// UploadMedia uploads media bytes for an account and returns the media id to
// attach to a subsequent Post.
func (a *Agent) UploadMedia(ctx context.Context, accountName string, data []byte, mediaType string) (string, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return "", err
	}
	return cl.UploadMedia(ctx, data, mediaType, "")
}

// Like favourites a tweet for an account.
func (a *Agent) Like(ctx context.Context, accountName, tweetID string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.Like(ctx, tweetID) })
}

// Unlike removes a favourite for an account.
func (a *Agent) Unlike(ctx context.Context, accountName, tweetID string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.Unlike(ctx, tweetID) })
}

// Retweet reposts for an account.
func (a *Agent) Retweet(ctx context.Context, accountName, tweetID string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.Retweet(ctx, tweetID) })
}

// Unretweet undoes a repost for an account.
func (a *Agent) Unretweet(ctx context.Context, accountName, tweetID string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.Unretweet(ctx, tweetID) })
}

// Delete removes a tweet for an account.
func (a *Agent) Delete(ctx context.Context, accountName, tweetID string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.Delete(ctx, tweetID) })
}

// Bookmark saves a tweet for an account.
func (a *Agent) Bookmark(ctx context.Context, accountName, tweetID string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.Bookmark(ctx, tweetID) })
}

// Unbookmark removes a saved tweet for an account.
func (a *Agent) Unbookmark(ctx context.Context, accountName, tweetID string) error {
	return a.act(ctx, accountName, func(c *xclient.Client) error { return c.Unbookmark(ctx, tweetID) })
}

func (a *Agent) act(ctx context.Context, accountName string, fn func(*xclient.Client) error) error {
	cl, err := a.client(accountName)
	if err != nil {
		return err
	}
	return fn(cl)
}
```

## File: pkg/agent/oauth.go
size: 1018
sha: 965ab1f2f9751cc4fd38178781728dee366cfac9
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/agent/oauth.go

```text
package agent

import (
	"context"

	"github.com/dezxbt/agentx/pkg/xclient"
)

// OAuthAuthorize inspects an OAuth2 authorization request on behalf of an
// account: returns the app metadata and requested scopes without approving.
func (a *Agent) OAuthAuthorize(ctx context.Context, accountName, authorizeURL string) (*xclient.OAuthConsent, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	return cl.OAuthAuthorize(ctx, authorizeURL)
}

// OAuthApprove auto-approves an OAuth2 consent request (Sign-in-with-X) using
// the account's session cookies — the programmatic equivalent of clicking
// "Authorize app" on the consent screen. With inspect=true nothing is
// approved; the caller only gets the app name and scope list.
func (a *Agent) OAuthApprove(ctx context.Context, accountName, authorizeURL string, inspect bool) (*xclient.OAuthApproval, error) {
	cl, err := a.client(accountName)
	if err != nil {
		return nil, err
	}
	return cl.OAuthApprove(ctx, authorizeURL, inspect)
}
```

## File: pkg/backends/fxtwitter/fxtwitter.go
size: 4058
sha: c57d3572575682875466e893cf9685ec0cd27d85
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/backends/fxtwitter/fxtwitter.go

```text
// Package fxtwitter is a zero-auth fallback backend for fetching single tweets
// via the public FxTwitter API (https://github.com/FxEmbed/FxEmbed). It needs
// no cookies, so agents can read a tweet even with no account configured.
package fxtwitter

import (
	"context"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"time"

	"github.com/dezxbt/agentx/pkg/models"
	"github.com/dezxbt/agentx/pkg/xerrors"
)

const apiBase = "https://api.fxtwitter.com"

// Client fetches tweets from FxTwitter.
type Client struct {
	httpClient *http.Client
	userAgent  string
}

// New builds a Client. A nil http client uses a sane default.
func New(hc *http.Client) *Client {
	if hc == nil {
		hc = &http.Client{Timeout: 30 * time.Second}
	}
	return &Client{httpClient: hc, userAgent: "Mozilla/5.0 (compatible; agentx/1.0)"}
}

type apiResponse struct {
	Code    int       `json:"code"`
	Message string    `json:"message"`
	Tweet   *apiTweet `json:"tweet"`
}

type apiTweet struct {
	URL       string    `json:"url"`
	ID        string    `json:"id"`
	Text      string    `json:"text"`
	Lang      string    `json:"lang"`
	CreatedAt string    `json:"created_at"`
	Likes     int       `json:"likes"`
	Retweets  int       `json:"retweets"`
	Replies   int       `json:"replies"`
	Views     int       `json:"views"`
	Bookmarks int       `json:"bookmarks"`
	Author    apiAuthor `json:"author"`
	Media     *apiMedia `json:"media"`
	Quote     *apiTweet `json:"quote"`
	// FxTwitter exposes reply linkage as a screen name plus the parent id.
	ReplyingTo       string `json:"replying_to"`
	ReplyingToStatus string `json:"replying_to_status"`
}

type apiAuthor struct {
	ID         string `json:"id"`
	Name       string `json:"name"`
	ScreenName string `json:"screen_name"`
	AvatarURL  string `json:"avatar_url"`
}

type apiMedia struct {
	All []apiMediaItem `json:"all"`
}

type apiMediaItem struct {
	Type   string `json:"type"`
	URL    string `json:"url"`
	Width  int    `json:"width"`
	Height int    `json:"height"`
}

// GetTweet fetches a single tweet by id.
func (c *Client) GetTweet(ctx context.Context, id string) (*models.Tweet, error) {
	url := fmt.Sprintf("%s/i/status/%s", apiBase, id)
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
	if err != nil {
		return nil, xerrors.Wrap(xerrors.InvalidInput, err, "build request")
	}
	req.Header.Set("User-Agent", c.userAgent)

	resp, err := c.httpClient.Do(req)
	if err != nil {
		return nil, xerrors.Wrap(xerrors.NetworkError, err, "fxtwitter request failed")
	}
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)

	if resp.StatusCode == http.StatusNotFound {
		return nil, xerrors.New(xerrors.NotFound, "tweet %s not found", id)
	}
	if resp.StatusCode != http.StatusOK {
		return nil, xerrors.New(xerrors.APIError, "fxtwitter returned %d", resp.StatusCode)
	}

	var out apiResponse
	if err := json.Unmarshal(body, &out); err != nil {
		return nil, xerrors.Wrap(xerrors.APIError, err, "decode fxtwitter response")
	}
	if out.Tweet == nil {
		return nil, xerrors.New(xerrors.NotFound, "tweet %s not available", id)
	}
	return convert(out.Tweet), nil
}

func convert(t *apiTweet) *models.Tweet {
	if t == nil {
		return nil
	}
	out := &models.Tweet{
		ID:        t.ID,
		Text:      t.Text,
		CreatedAt: t.CreatedAt,
		Lang:      t.Lang,
		Author: models.Author{
			ID:              t.Author.ID,
			Name:            t.Author.Name,
			ScreenName:      t.Author.ScreenName,
			ProfileImageURL: t.Author.AvatarURL,
		},
		Metrics: models.Metrics{
			Likes:     t.Likes,
			Retweets:  t.Retweets,
			Replies:   t.Replies,
			Views:     t.Views,
			Bookmarks: t.Bookmarks,
		},
		Source: "fxtwitter",
	}
	out.InReplyToID = t.ReplyingToStatus
	out.InReplyToUser = t.ReplyingTo
	out.ConversationID = t.ReplyingToStatus
	out.IsReply = t.ReplyingToStatus != "" || t.ReplyingTo != ""
	if t.Media != nil {
		for _, m := range t.Media.All {
			out.Media = append(out.Media, models.Media{
				Type: m.Type, URL: m.URL, Width: m.Width, Height: m.Height,
			})
		}
	}
	out.QuotedTweet = convert(t.Quote)
	return out
}
```

## File: pkg/models/models.go
size: 4000
sha: 7579b660d67250eb8bee009a27192830a762b214
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/models/models.go

```text
// Package models holds the shared, backend-agnostic data types returned by the
// agentx client. Every fetch backend (authenticated GraphQL, FxTwitter, ...)
// normalises its raw payload into these types so agents see one stable schema.
package models

// Author is the user that produced a tweet.
type Author struct {
	ID              string `json:"id"`
	Name            string `json:"name"`
	ScreenName      string `json:"screenName"`
	ProfileImageURL string `json:"profileImageUrl,omitempty"`
	Verified        bool   `json:"verified,omitempty"`
}

// Metrics holds public engagement counters.
type Metrics struct {
	Likes     int `json:"likes"`
	Retweets  int `json:"retweets"`
	Replies   int `json:"replies"`
	Quotes    int `json:"quotes"`
	Views     int `json:"views"`
	Bookmarks int `json:"bookmarks"`
}

// Media is an attached photo, video or animated gif.
type Media struct {
	Type   string `json:"type"`
	URL    string `json:"url"`
	Width  int    `json:"width,omitempty"`
	Height int    `json:"height,omitempty"`
}

// PollChoice is one option of a poll plus the vote count x.com reports for it.
type PollChoice struct {
	Label string `json:"label"`
	Count int    `json:"count"`
}

// Poll is the poll attached to a tweet. x.com delivers a poll as a card, not as
// a typed object, so these fields are decoded from the card's binding_values.
type Poll struct {
	Choices         []PollChoice `json:"choices"`
	EndsAt          string       `json:"endsAt,omitempty"`
	DurationMinutes int          `json:"durationMinutes,omitempty"`
	Final           bool         `json:"final,omitempty"` // counts_are_final
	Selected        int          `json:"selected,omitempty"`
}

// Tweet is the normalised representation of a single tweet.
type Tweet struct {
	ID            string   `json:"id"`
	Text          string   `json:"text"`
	Author        Author   `json:"author"`
	Metrics       Metrics  `json:"metrics"`
	CreatedAt     string   `json:"createdAt,omitempty"`
	Media         []Media  `json:"media,omitempty"`
	URLs          []string `json:"urls,omitempty"`
	IsRetweet     bool     `json:"isRetweet,omitempty"`
	RetweetedBy   string   `json:"retweetedBy,omitempty"`
	IsReply       bool     `json:"isReply,omitempty"`
	InReplyToID   string   `json:"inReplyToId,omitempty"`
	InReplyToUser string   `json:"inReplyToUser,omitempty"`
	// ConversationID is the root tweet of the thread. Equal to ID for a tweet
	// that starts a thread, so it is what tells a client which thread a reply
	// landed in without fetching the parent.
	ConversationID string `json:"conversationId,omitempty"`
	Lang           string `json:"lang,omitempty"`
	QuotedTweet    *Tweet `json:"quotedTweet,omitempty"`
	Poll           *Poll  `json:"poll,omitempty"`
	ArticleTitle   string `json:"articleTitle,omitempty"`
	ArticleText    string `json:"articleText,omitempty"`
	Source         string `json:"source,omitempty"` // which backend produced this tweet
}

// UserProfile is the normalised representation of a user.
type UserProfile struct {
	ID              string `json:"id"`
	Name            string `json:"name"`
	ScreenName      string `json:"screenName"`
	Bio             string `json:"bio,omitempty"`
	Location        string `json:"location,omitempty"`
	URL             string `json:"url,omitempty"`
	FollowersCount  int    `json:"followersCount"`
	FollowingCount  int    `json:"followingCount"`
	TweetsCount     int    `json:"tweetsCount"`
	Verified        bool   `json:"verified,omitempty"`
	ProfileImageURL string `json:"profileImageUrl,omitempty"`
	CreatedAt       string `json:"createdAt,omitempty"`
}

// Page is a paginated slice of tweets with an optional continuation cursor.
type Page struct {
	Tweets     []Tweet `json:"tweets"`
	NextCursor string  `json:"nextCursor,omitempty"`
}

// UserPage is a paginated slice of users (followers/following) with an optional
// continuation cursor.
type UserPage struct {
	Users      []UserProfile `json:"users"`
	NextCursor string        `json:"nextCursor,omitempty"`
}
```

## File: pkg/transaction/animate.go
size: 605
sha: 17ba7874e1bbca5bca52dd040244007e41e22c7a
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/transaction/animate.go

```text
package transaction

import "math"

// interpolate ports interpolate.interpolate (numeric branch only; the boolean
// branch in the Python source is never reached for this library's inputs).
func interpolate(from, to []float64, f float64) []float64 {
	out := make([]float64, len(from))
	for i := range from {
		out[i] = from[i]*(1-f) + to[i]*f
	}
	return out
}

// convertRotationToMatrix ports rotation.convert_rotation_to_matrix.
func convertRotationToMatrix(rotation float64) []float64 {
	rad := rotation * math.Pi / 180
	return []float64{math.Cos(rad), -math.Sin(rad), math.Sin(rad), math.Cos(rad)}
}
```

## File: pkg/transaction/constants.go
size: 1949
sha: 72e5bc2facc7af31f0e87b808767cf4878760349
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/transaction/constants.go

```text
// Package transaction is a faithful Go port of iSarabjitDhiman/XClientTransaction.
//
// It generates the `x-client-transaction-id` header that x.com expects on its
// internal GraphQL / REST endpoints. Sending a correct transaction id on every
// authenticated request makes traffic look like a real browser session, which
// is the single biggest factor in keeping `auth_token` cookies alive instead of
// getting them flagged and expired early.
package transaction

import "regexp"

const (
	// additionalRandomNumber is the static byte appended to the payload before
	// the XOR masking step. Ported from constants.ADDITIONAL_RANDOM_NUMBER.
	additionalRandomNumber = 3

	// defaultKeyword is the obfuscation keyword folded into the SHA-256 input.
	// Ported from constants.DEFAULT_KEYWORD.
	defaultKeyword = "obfiowerehiring"

	// onDemandFileURLTemplate builds the ondemand.s JS file URL from its hash.
	onDemandFileURLTemplate = "https://abs.twimg.com/responsive-web/client-web/ondemand.s.%sa.js"

	// epochOffsetMillis is subtracted from the current unix-millis timestamp.
	// 1682924400 seconds ~= 2023-04-23T00:00:00Z. Ported from the literal
	// 1682924400 * 1000 in generate_transaction_id.
	epochOffsetMillis = 1682924400 * 1000

	// totalTime is the animation frame-time normaliser.
	totalTime = 4096
)

var (
	// onDemandFileRegex finds the ondemand.s file index in the home page HTML.
	// Python: r""",(\d+):["']ondemand\.s["']"""
	onDemandFileRegex = regexp.MustCompile(`,(\d+):["']ondemand\.s["']`)

	// indicesRegex extracts the key-byte indices from the ondemand.s JS file.
	// Python: r"""(\(\w{1}\[(\d{1,2})\],\s*16\))+"""
	indicesRegex = regexp.MustCompile(`\(\w\[(\d{1,2})\],\s*16\)`)
)

// onDemandHashPattern builds the per-index hash extraction regex. Python:
// r',{}:\"([0-9a-f]+)\"'.
func onDemandHashPattern(index string) *regexp.Regexp {
	return regexp.MustCompile(`,` + regexp.QuoteMeta(index) + `:"([0-9a-f]+)"`)
}
```

## File: pkg/transaction/cubic.go
size: 1316
sha: 5c4c03b0835d8a8885217b8df5fddfe02f162d82
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/transaction/cubic.go

```text
package transaction

// cubic ports cubic_curve.Cubic: a cubic Bézier solver over four control
// values [x1, y1, x2, y2].
type cubic struct {
	curves []float64
}

func newCubic(curves []float64) *cubic { return &cubic{curves: curves} }

func (c *cubic) getValue(t float64) float64 {
	var startGradient, endGradient float64
	start, mid, end := 0.0, 0.0, 1.0

	if t <= 0.0 {
		if c.curves[0] > 0.0 {
			startGradient = c.curves[1] / c.curves[0]
		} else if c.curves[1] == 0.0 && c.curves[2] > 0.0 {
			startGradient = c.curves[3] / c.curves[2]
		}
		return startGradient * t
	}

	if t >= 1.0 {
		if c.curves[2] < 1.0 {
			endGradient = (c.curves[3] - 1.0) / (c.curves[2] - 1.0)
		} else if c.curves[2] == 1.0 && c.curves[0] < 1.0 {
			endGradient = (c.curves[1] - 1.0) / (c.curves[0] - 1.0)
		}
		return 1.0 + endGradient*(t-1.0)
	}

	for start < end {
		mid = (start + end) / 2
		xEst := cubicCalculate(c.curves[0], c.curves[2], mid)
		if abs(t-xEst) < 0.00001 {
			return cubicCalculate(c.curves[1], c.curves[3], mid)
		}
		if xEst < t {
			start = mid
		} else {
			end = mid
		}
	}
	return cubicCalculate(c.curves[1], c.curves[3], mid)
}

func cubicCalculate(a, b, m float64) float64 {
	return 3.0*a*(1-m)*(1-m)*m + 3.0*b*(1-m)*m*m + m*m*m
}

func abs(x float64) float64 {
	if x < 0 {
		return -x
	}
	return x
}
```

## File: pkg/transaction/mathutil.go
size: 2093
sha: 126eb7ff01066ee91a16cc139554154e6355333f
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/transaction/mathutil.go

```text
package transaction

import (
	"math"
	"strconv"
)

// roundTo replicates Python's round(x, n). CPython rounds half-to-even on the
// true decimal value; Go's strconv.FormatFloat uses the same round-half-to-even
// rule on the exact binary value, so formatting and re-parsing reproduces
// Python's result bit-for-bit for the inputs this library deals with.
func roundTo(x float64, n int) float64 {
	v, _ := strconv.ParseFloat(strconv.FormatFloat(x, 'f', n, 64), 64)
	return v
}

// roundHalfEven replicates Python's round(x) -> int (banker's rounding).
func roundHalfEven(x float64) int {
	v, _ := strconv.ParseInt(strconv.FormatFloat(x, 'f', 0, 64), 10, 64)
	return int(v)
}

// mathRound ports utils.Math.round: floor, bump to ceil on >= .5, keep sign.
func mathRound(num float64) float64 {
	x := math.Floor(num)
	if num-x >= 0.5 {
		x = math.Ceil(num)
	}
	return math.Copysign(x, num)
}

// solve ports ClientTransaction.solve.
func solve(value, minVal, maxVal float64, rounding bool) float64 {
	result := value*(maxVal-minVal)/255 + minVal
	if rounding {
		return math.Floor(result)
	}
	return roundTo(result, 2)
}

// isOdd ports utils.is_odd: -1.0 for odd, 0.0 for even.
func isOdd(n int) float64 {
	if n%2 != 0 {
		return -1.0
	}
	return 0.0
}

// floatToHex ports utils.float_to_hex, including its uppercase A-F digits and
// the leading-dot behaviour for pure fractions.
func floatToHex(x float64) string {
	var result []byte
	quotient := int(x)
	fraction := x - float64(quotient)

	for quotient > 0 {
		quotient = int(x / 16)
		remainder := int(x - float64(quotient)*16)
		if remainder > 9 {
			result = append([]byte{byte(remainder + 55)}, result...)
		} else {
			result = append([]byte{byte(remainder + '0')}, result...)
		}
		x = float64(quotient)
	}

	if fraction == 0 {
		return string(result)
	}

	result = append(result, '.')
	for fraction > 0 {
		fraction *= 16
		integer := int(fraction)
		fraction -= float64(integer)
		if integer > 9 {
			result = append(result, byte(integer+55))
		} else {
			result = append(result, byte(integer+'0'))
		}
	}
	return string(result)
}
```

## File: pkg/transaction/parse.go
size: 2771
sha: 4989ec740b5976325c7b4ee14243f38686161d79
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/transaction/parse.go

```text
package transaction

import (
	"fmt"
	"regexp"
	"strconv"
	"strings"

	"github.com/PuerkitoBio/goquery"
)

var digitsRegex = regexp.MustCompile(`\d+`)

// getKey extracts the twitter-site-verification key from the home page.
func getKey(doc *goquery.Document) (string, error) {
	v, ok := doc.Find("meta[name='twitter-site-verification']").First().Attr("content")
	if !ok || v == "" {
		return "", fmt.Errorf("transaction: couldn't get [twitter-site-verification] key from page source")
	}
	return v, nil
}

// getFrames returns the loading-x-anim animation frame elements.
func getFrames(doc *goquery.Document) *goquery.Selection {
	return doc.Find("[id^='loading-x-anim']")
}

// get2DArray ports ClientTransaction.get_2d_array. It selects the frame at
// keyBytes[5]%4, reads the second path's "d" attribute, drops the first 9
// characters, splits on "C", and parses each segment's digit runs.
func get2DArray(doc *goquery.Document, keyBytes []int) ([][]int, error) {
	frames := getFrames(doc)
	if frames.Length() == 0 {
		return nil, fmt.Errorf("transaction: no loading-x-anim frames found")
	}
	frame := frames.Eq(keyBytes[5] % 4)
	d, ok := frame.Children().Eq(0).Children().Eq(1).Attr("d")
	if !ok || len(d) < 9 {
		return nil, fmt.Errorf("transaction: animation frame path data missing or too short")
	}
	segments := strings.Split(d[9:], "C")
	out := make([][]int, 0, len(segments))
	for _, seg := range segments {
		nums := digitsRegex.FindAllString(seg, -1)
		row := make([]int, 0, len(nums))
		for _, n := range nums {
			i, _ := strconv.Atoi(n)
			row = append(row, i)
		}
		out = append(out, row)
	}
	return out, nil
}

// getIndices ports ClientTransaction.get_indices over the ondemand.s text.
func getIndices(ondemandText string) (rowIndex int, keyBytesIndices []int, err error) {
	matches := indicesRegex.FindAllStringSubmatch(ondemandText, -1)
	if len(matches) == 0 {
		return 0, nil, fmt.Errorf("transaction: couldn't get KEY_BYTE indices")
	}
	all := make([]int, 0, len(matches))
	for _, m := range matches {
		i, convErr := strconv.Atoi(m[1])
		if convErr != nil {
			return 0, nil, fmt.Errorf("transaction: bad index %q: %w", m[1], convErr)
		}
		all = append(all, i)
	}
	return all[0], all[1:], nil
}

// getOndemandFileURL ports utils.get_ondemand_file_url over the raw home HTML.
func getOndemandFileURL(homeHTML string) (string, error) {
	idxMatch := onDemandFileRegex.FindStringSubmatch(homeHTML)
	if idxMatch == nil {
		return "", fmt.Errorf("transaction: couldn't locate ondemand.s file index")
	}
	hashMatch := onDemandHashPattern(idxMatch[1]).FindStringSubmatch(homeHTML)
	if hashMatch == nil {
		return "", fmt.Errorf("transaction: couldn't locate ondemand.s file hash")
	}
	return fmt.Sprintf(onDemandFileURLTemplate, hashMatch[1]), nil
}
```

## File: pkg/transaction/provider.go
size: 5089
sha: db3c5d82a3dab4a457912b71495f7928d6673a9a
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/transaction/provider.go

```text
package transaction

import (
	"fmt"
	"io"
	"net/http"
	"net/url"
	"sync"
	"time"
)

// DefaultUserAgent matches a recent desktop Chrome, consistent with the headers
// xclient sends on API calls.
const DefaultUserAgent = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/127.0.0.0 Safari/537.36"

// Provider fetches and caches the data needed to build a Generator (the x.com
// home page and its ondemand.s file), refreshing it after TTL. The verification
// and animation keys rotate infrequently, so a long TTL keeps requests cheap
// while still looking like a live browser session.
type Provider struct {
	httpClient *http.Client
	userAgent  string
	ttl        time.Duration

	// cookie is the account cookie string sent when fetching x.com. x.com only
	// serves the responsive-web chunk map (the `,<idx>:"ondemand.s"` entry the
	// generator needs) to an authenticated session; the logged-out shell this
	// provider used to request does not contain it, which made every
	// transaction-id generation fail. Writes are fatal on that failure, so
	// posts/likes/DMs/Grok all errored with "generate x-client-transaction-id".
	cookie string

	mu        sync.Mutex
	gen       *Generator
	fetchedAt time.Time
}

// ProviderOption customises a Provider.
type ProviderOption func(*Provider)

// WithHTTPClient sets the HTTP client used to fetch x.com (share this with the
// API client so both present the same TLS fingerprint).
func WithHTTPClient(c *http.Client) ProviderOption {
	return func(p *Provider) { p.httpClient = c }
}

// WithUserAgent sets the User-Agent used when fetching x.com.
func WithUserAgent(ua string) ProviderOption {
	return func(p *Provider) { p.userAgent = ua }
}

// WithTTL sets how long fetched home/ondemand data is reused (default 3h).
func WithTTL(d time.Duration) ProviderOption {
	return func(p *Provider) { p.ttl = d }
}

// WithCookie sets the account cookie string used when fetching x.com. Required:
// x.com only serves the chunk map the generator parses to authenticated
// sessions (see Provider.cookie).
func WithCookie(cookie string) ProviderOption {
	return func(p *Provider) { p.cookie = cookie }
}

// SetCookie updates the cookie used for x.com fetches. Safe to call per client
// even when the provider is shared: the cached Generator is account-independent,
// so an update only affects the next refresh.
func (p *Provider) SetCookie(cookie string) {
	p.mu.Lock()
	p.cookie = cookie
	p.mu.Unlock()
}

// NewProvider creates a Provider with sensible defaults.
func NewProvider(opts ...ProviderOption) *Provider {
	p := &Provider{
		httpClient: &http.Client{Timeout: 30 * time.Second},
		userAgent:  DefaultUserAgent,
		ttl:        3 * time.Hour,
	}
	for _, o := range opts {
		o(p)
	}
	return p
}

// TransactionID returns a fresh x-client-transaction-id for the method/path,
// refreshing the underlying keys if the cache has expired.
func (p *Provider) TransactionID(method, path string) (string, error) {
	g, err := p.generator()
	if err != nil {
		return "", err
	}
	return g.GenerateTransactionID(method, path), nil
}

func (p *Provider) generator() (*Generator, error) {
	p.mu.Lock()
	defer p.mu.Unlock()
	if p.gen != nil && time.Since(p.fetchedAt) < p.ttl {
		return p.gen, nil
	}
	if err := p.refreshLocked(); err != nil {
		if p.gen != nil {
			return p.gen, nil // fall back to stale keys rather than failing the request
		}
		return nil, err
	}
	return p.gen, nil
}

func (p *Provider) refreshLocked() error {
	homeHTML, err := p.fetch("https://x.com", p.cookie)
	if err != nil {
		return fmt.Errorf("transaction: fetch home page: %w", err)
	}
	ondemandURL, err := getOndemandFileURL(homeHTML)
	if err != nil {
		return err
	}
	// The ondemand.s file is a static asset on abs.twimg.com: send no cookies.
	ondemandText, err := p.fetch(ondemandURL, "")
	if err != nil {
		return fmt.Errorf("transaction: fetch ondemand file: %w", err)
	}
	gen, err := New(homeHTML, ondemandText)
	if err != nil {
		return err
	}
	p.gen = gen
	p.fetchedAt = time.Now()
	return nil
}

func (p *Provider) fetch(rawURL, cookie string) (string, error) {
	req, err := http.NewRequest(http.MethodGet, rawURL, nil)
	if err != nil {
		return "", err
	}
	req.Header.Set("User-Agent", p.userAgent)
	req.Header.Set("Accept", "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8")
	req.Header.Set("Accept-Language", "en-US,en;q=0.9")
	req.Header.Set("Referer", "https://x.com")
	req.Header.Set("Cache-Control", "no-cache")
	// Only x.com serves the chunk map, and only to an authenticated session.
	// Never send the account cookies to the static asset host.
	if u, perr := url.Parse(rawURL); perr == nil && u.Host == "x.com" && cookie != "" {
		req.Header.Set("Cookie", cookie)
	}

	resp, err := p.httpClient.Do(req)
	if err != nil {
		return "", err
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		return "", fmt.Errorf("transaction: %s returned status %d", rawURL, resp.StatusCode)
	}
	body, err := io.ReadAll(resp.Body)
	if err != nil {
		return "", err
	}
	return string(body), nil
}
```

## File: pkg/transaction/provider_test.go
size: 2314
sha: 253ac939de55aeb9276f16713997870e2b6c2fc4
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/transaction/provider_test.go

```text
package transaction

import (
	"io"
	"net/http"
	"strings"
	"testing"
)

// captureRT records the last request it saw so tests can assert on headers.
type captureRT struct{ req *http.Request }

func (c *captureRT) RoundTrip(r *http.Request) (*http.Response, error) {
	c.req = r
	return &http.Response{
		StatusCode: http.StatusOK,
		Body:       io.NopCloser(strings.NewReader("<html></html>")),
		Header:     make(http.Header),
	}, nil
}

func newTestProvider(rt *captureRT, cookie string) *Provider {
	return NewProvider(
		WithHTTPClient(&http.Client{Transport: rt}),
		WithCookie(cookie),
	)
}

func TestProviderCookieOptions(t *testing.T) {
	p := NewProvider(WithCookie("auth_token=a; ct0=b"))
	if p.cookie != "auth_token=a; ct0=b" {
		t.Fatalf("WithCookie not applied: %q", p.cookie)
	}
	p.SetCookie("auth_token=c")
	if p.cookie != "auth_token=c" {
		t.Fatalf("SetCookie not applied: %q", p.cookie)
	}
}

// x.com only serves the responsive-web chunk map (the `,<idx>:"ondemand.s"`
// entry getOndemandFileURL parses) to an authenticated session, so the home
// page fetch must carry the account cookie — and only that host may see it.
func TestProviderFetchCookieScope(t *testing.T) {
	rt := &captureRT{}
	p := newTestProvider(rt, "auth_token=a; ct0=b")

	if _, err := p.fetch("https://x.com/", p.cookie); err != nil {
		t.Fatalf("fetch x.com: %v", err)
	}
	if got := rt.req.Header.Get("Cookie"); got != "auth_token=a; ct0=b" {
		t.Fatalf("x.com home fetch must send the account cookie, got %q", got)
	}
	if got := rt.req.Header.Get("User-Agent"); got == "" {
		t.Fatal("home fetch lost its User-Agent")
	}

	// The ondemand.s file is a static asset on abs.twimg.com: no cookies.
	if _, err := p.fetch("https://abs.twimg.com/responsive-web/client-web/ondemand.s.deadbeef1a.js", ""); err != nil {
		t.Fatalf("fetch asset: %v", err)
	}
	if got := rt.req.Header.Get("Cookie"); got != "" {
		t.Fatalf("static asset host must not receive the account cookie, got %q", got)
	}

	// Belt and braces: even if a cookie is passed in, a non-x.com host is refused.
	if _, err := p.fetch("https://example.com/", "auth_token=a"); err != nil {
		t.Fatalf("fetch other host: %v", err)
	}
	if got := rt.req.Header.Get("Cookie"); got != "" {
		t.Fatalf("non-x.com host must not receive the account cookie, got %q", got)
	}
}
```

## File: pkg/transaction/transaction.go
size: 6037
sha: 3bd0e883c24019956dc72d6f67026371ec33b69d
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/transaction/transaction.go

```text
package transaction

import (
	"crypto/sha256"
	"encoding/base64"
	"fmt"
	"math"
	"math/rand"
	"net/url"
	"regexp"
	"strconv"
	"strings"
	"time"

	"github.com/PuerkitoBio/goquery"
)

// Generator is a faithful port of XClientTransaction.ClientTransaction. It is
// safe for concurrent use: GenerateTransactionID only reads immutable state and
// uses package-level randomness.
type Generator struct {
	doc              *goquery.Document
	key              string
	keyBytes         []int
	animationKey     string
	rowIndex         int
	keyBytesIndices  []int
	randomKeyword    string
	additionalNumber int
}

// Option customises a Generator.
type Option func(*Generator)

// WithKeyword overrides the obfuscation keyword (defaults to "obfiowerehiring").
func WithKeyword(k string) Option { return func(g *Generator) { g.randomKeyword = k } }

// WithNumber overrides the static appended byte (defaults to 3).
func WithNumber(n int) Option { return func(g *Generator) { g.additionalNumber = n } }

var dotDashRegex = regexp.MustCompile(`[.-]`)

// New builds a Generator from the x.com home page HTML and the ondemand.s file
// text. Both are fetched without authentication (see Provider for a helper that
// retrieves and caches them).
func New(homeHTML, ondemandText string, opts ...Option) (*Generator, error) {
	doc, err := goquery.NewDocumentFromReader(strings.NewReader(homeHTML))
	if err != nil {
		return nil, fmt.Errorf("transaction: parse home page: %w", err)
	}

	g := &Generator{
		doc:              doc,
		randomKeyword:    defaultKeyword,
		additionalNumber: additionalRandomNumber,
	}
	for _, o := range opts {
		o(g)
	}

	if g.rowIndex, g.keyBytesIndices, err = getIndices(ondemandText); err != nil {
		return nil, err
	}
	if g.key, err = getKey(doc); err != nil {
		return nil, err
	}
	keyBytes, err := decodeKeyBytes(g.key)
	if err != nil {
		return nil, err
	}
	g.keyBytes = keyBytes
	if g.animationKey, err = g.getAnimationKey(); err != nil {
		return nil, err
	}
	return g, nil
}

func decodeKeyBytes(key string) ([]int, error) {
	raw, err := base64.StdEncoding.DecodeString(key)
	if err != nil {
		return nil, fmt.Errorf("transaction: decode verification key: %w", err)
	}
	out := make([]int, len(raw))
	for i, b := range raw {
		out[i] = int(b)
	}
	return out, nil
}

func (g *Generator) getAnimationKey() (string, error) {
	rowIndex := g.keyBytes[g.rowIndex] % 16

	frameTime := 1
	for _, idx := range g.keyBytesIndices {
		frameTime *= g.keyBytes[idx] % 16
	}
	frameTimeF := mathRound(float64(frameTime)/10) * 10

	arr, err := get2DArray(g.doc, g.keyBytes)
	if err != nil {
		return "", err
	}
	if rowIndex >= len(arr) {
		return "", fmt.Errorf("transaction: frame row index %d out of range (%d rows)", rowIndex, len(arr))
	}
	frameRow := arr[rowIndex]
	if len(frameRow) < 11 {
		return "", fmt.Errorf("transaction: frame row too short (%d values)", len(frameRow))
	}

	targetTime := frameTimeF / totalTime
	return animate(frameRow, targetTime), nil
}

// animate ports ClientTransaction.animate.
func animate(frames []int, targetTime float64) string {
	fromColor := []float64{float64(frames[0]), float64(frames[1]), float64(frames[2]), 1}
	toColor := []float64{float64(frames[3]), float64(frames[4]), float64(frames[5]), 1}
	fromRotation := []float64{0.0}
	toRotation := []float64{solve(float64(frames[6]), 60.0, 360.0, true)}

	rest := frames[7:]
	curves := make([]float64, len(rest))
	for i, item := range rest {
		curves[i] = solve(float64(item), isOdd(i), 1.0, false)
	}

	val := newCubic(curves).getValue(targetTime)

	color := interpolate(fromColor, toColor, val)
	for i := range color {
		color[i] = math.Max(0, math.Min(255, color[i]))
	}
	rotation := interpolate(fromRotation, toRotation, val)
	matrix := convertRotationToMatrix(rotation[0])

	var sb strings.Builder
	for _, value := range color[:len(color)-1] {
		sb.WriteString(strconv.FormatInt(int64(roundHalfEven(value)), 16))
	}
	for _, value := range matrix {
		rounded := roundTo(value, 2)
		if rounded < 0 {
			rounded = -rounded
		}
		hexValue := floatToHex(rounded)
		switch {
		case strings.HasPrefix(hexValue, "."):
			sb.WriteString(strings.ToLower("0" + hexValue))
		case hexValue != "":
			sb.WriteString(hexValue)
		default:
			sb.WriteString("0")
		}
	}
	sb.WriteString("00")

	return dotDashRegex.ReplaceAllString(sb.String(), "")
}

// GenerateTransactionID produces the x-client-transaction-id value for an HTTP
// method and request path (e.g. "/i/api/graphql/<qid>/UserByScreenName").
func (g *Generator) GenerateTransactionID(method, path string) string {
	timeNow := int64(math.Floor(float64(time.Now().UnixMilli()-epochOffsetMillis) / 1000))
	timeNowBytes := []int{
		int(timeNow & 0xFF),
		int((timeNow >> 8) & 0xFF),
		int((timeNow >> 16) & 0xFF),
		int((timeNow >> 24) & 0xFF),
	}

	input := fmt.Sprintf("%s!%s!%d%s%s", method, path, timeNow, g.randomKeyword, g.animationKey)
	sum := sha256.Sum256([]byte(input))

	bytesArr := make([]int, 0, len(g.keyBytes)+4+16+1)
	bytesArr = append(bytesArr, g.keyBytes...)
	bytesArr = append(bytesArr, timeNowBytes...)
	for _, b := range sum[:16] {
		bytesArr = append(bytesArr, int(b))
	}
	bytesArr = append(bytesArr, g.additionalNumber)

	randomNum := rand.Intn(256)
	out := make([]byte, 0, len(bytesArr)+1)
	out = append(out, byte(randomNum))
	for _, item := range bytesArr {
		out = append(out, byte(item^randomNum))
	}

	return strings.TrimRight(base64.StdEncoding.EncodeToString(out), "=")
}

// GenerateForURL is a convenience wrapper that extracts the path from a full URL.
func (g *Generator) GenerateForURL(method, rawURL string) (string, error) {
	u, err := url.Parse(rawURL)
	if err != nil {
		return "", fmt.Errorf("transaction: parse url: %w", err)
	}
	return g.GenerateTransactionID(method, u.Path), nil
}

// Key returns the verification key extracted from the home page.
func (g *Generator) Key() string { return g.key }

// AnimationKey returns the computed animation key (useful for debugging/tests).
func (g *Generator) AnimationKey() string { return g.animationKey }
```

## File: pkg/transaction/transaction_test.go
size: 2234
sha: ab75c8b5e3aa7a90ece89e1378db71f12d7a87da
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/transaction/transaction_test.go

```text
package transaction

import (
	"encoding/base64"
	"os"
	"strings"
	"testing"
)

// golden values produced by the reference Python XClientTransaction library
// (iSarabjitDhiman/XClientTransaction) on the same fixtures.
const (
	goldenAnimationKey = "7ad100ccccccccccccd00ccccccccccccd100"
	goldenRowIndex     = 2
)

func loadFixtures(t *testing.T) (home, ondemand string) {
	t.Helper()
	h, err := os.ReadFile("testdata/home.html")
	if err != nil {
		t.Fatalf("read home fixture: %v", err)
	}
	o, err := os.ReadFile("testdata/ondemand.js")
	if err != nil {
		t.Fatalf("read ondemand fixture: %v", err)
	}
	return string(h), string(o)
}

func TestParityWithPython(t *testing.T) {
	home, ondemand := loadFixtures(t)
	g, err := New(home, ondemand)
	if err != nil {
		t.Fatalf("New: %v", err)
	}
	if g.rowIndex != goldenRowIndex {
		t.Errorf("rowIndex = %d, want %d", g.rowIndex, goldenRowIndex)
	}
	if g.AnimationKey() != goldenAnimationKey {
		t.Errorf("animationKey = %q, want %q", g.AnimationKey(), goldenAnimationKey)
	}
}

func TestGenerateTransactionIDShape(t *testing.T) {
	home, ondemand := loadFixtures(t)
	g, err := New(home, ondemand)
	if err != nil {
		t.Fatalf("New: %v", err)
	}
	id := g.GenerateTransactionID("GET", "/i/api/graphql/abc/UserByScreenName")
	if id == "" {
		t.Fatal("empty transaction id")
	}
	if strings.HasSuffix(id, "=") {
		t.Errorf("transaction id should be unpadded: %q", id)
	}
	// must decode as standard base64 once padding is restored
	padded := id
	if m := len(padded) % 4; m != 0 {
		padded += strings.Repeat("=", 4-m)
	}
	if _, err := base64.StdEncoding.DecodeString(padded); err != nil {
		t.Errorf("transaction id is not valid base64: %v", err)
	}
	// two successive ids should differ (random byte + timestamp)
	if id2 := g.GenerateTransactionID("GET", "/i/api/graphql/abc/UserByScreenName"); id2 == id {
		t.Error("expected successive transaction ids to differ")
	}
}

func TestFloatToHex(t *testing.T) {
	// spot-checks mirroring the Python implementation's behaviour.
	cases := map[float64]string{
		0:   "",
		1:   "1",
		255: "FF",
		16:  "10",
	}
	for in, want := range cases {
		if got := floatToHex(in); got != want {
			t.Errorf("floatToHex(%v) = %q, want %q", in, got, want)
		}
	}
}
```

## File: pkg/xclient/article_test.go
size: 5374
sha: 9062679ed896cf04cc5eeb221a4c08677eba2eee
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/article_test.go

```text
package xclient

import (
	"testing"

	"github.com/dezxbt/agentx/pkg/models"
)

// richArticleResult mirrors the real article schema: an inline Bold range, plus
// atomic blocks whose entityRanges reference an entityMap (list of
// {key,value}) carrying DIVIDER, MARKDOWN and MEDIA entities, with media URLs
// resolved through media_entities.
const richArticleResult = `{ "article": { "article_results": { "result": {
  "title": "Rich",
  "media_entities": [
    { "media_id": "m1", "media_info": { "__typename": "ApiImage", "original_img_url": "https://img/x.jpg" } }
  ],
  "content_state": {
    "blocks": [
      { "type": "unstyled", "text": "Hello bold world",
        "inlineStyleRanges": [ { "offset": 6, "length": 4, "style": "Bold" } ], "entityRanges": [] },
      { "type": "atomic", "text": " ", "inlineStyleRanges": [], "entityRanges": [ { "key": 0, "length": 1, "offset": 0 } ] },
      { "type": "atomic", "text": " ", "inlineStyleRanges": [], "entityRanges": [ { "key": 1, "length": 1, "offset": 0 } ] },
      { "type": "atomic", "text": " ", "inlineStyleRanges": [], "entityRanges": [ { "key": 2, "length": 1, "offset": 0 } ] }
    ],
    "entityMap": [
      { "key": "0", "value": { "type": "DIVIDER", "data": {} } },
      { "key": "1", "value": { "type": "MARKDOWN", "data": { "markdown": "| a | b |\n|---|---|" } } },
      { "key": "2", "value": { "type": "MEDIA", "data": { "caption": "fig", "mediaItems": [ { "mediaId": "m1" } ] } } }
    ]
  }
} } } }`

func TestArticleEntitiesAndInlineMarkdown(t *testing.T) {
	tw := &models.Tweet{}
	fillArticle(tw, asMap(decode([]byte(richArticleResult))), true)
	want := "Hello **bold** world\n\n---\n\n| a | b |\n|---|---|\n\n![fig](https://img/x.jpg)"
	if tw.ArticleText != want {
		t.Errorf("markdown =\n%q\nwant\n%q", tw.ArticleText, want)
	}
}

func TestArticleEntitiesPlain(t *testing.T) {
	tw := &models.Tweet{}
	fillArticle(tw, asMap(decode([]byte(richArticleResult))), false)
	// plain: no inline marks, divider skipped, markdown + media captions kept
	want := "Hello bold world\n| a | b |\n|---|---|\nfig: https://img/x.jpg"
	if tw.ArticleText != want {
		t.Errorf("plain =\n%q\nwant\n%q", tw.ArticleText, want)
	}
}

func TestApplyInlineStylesNestedAndUnicode(t *testing.T) {
	// "a—b" has an en-dash (multi-byte in UTF-8, 1 UTF-16 unit); bold over "b".
	got := applyInlineStyles("a—b", []any{
		map[string]any{"offset": float64(2), "length": float64(1), "style": "Bold"},
	})
	if got != "a—**b**" {
		t.Errorf("got %q, want %q", got, "a—**b**")
	}
}

// sampleArticleTweet mirrors a TweetResultByRestId result for a long-form X
// Article: a normal tweet object plus an article.article_results.result holding
// a DraftJS content_state with assorted block types.
const sampleArticleTweet = `{
  "__typename": "Tweet",
  "rest_id": "456",
  "core": { "user_results": { "result": {
    "rest_id": "9",
    "core": { "name": "Jack", "screen_name": "jack" }
  } } },
  "legacy": { "full_text": "Read my article", "lang": "en" },
  "article": { "article_results": { "result": {
    "title": "My Great Article",
    "preview_text": "A short preview",
    "content_state": {
      "blocks": [
        { "type": "header-one", "text": "Intro" },
        { "type": "unstyled", "text": "First paragraph." },
        { "type": "ordered-list-item", "text": "step one" },
        { "type": "ordered-list-item", "text": "step two" },
        { "type": "unordered-list-item", "text": "a bullet" },
        { "type": "blockquote", "text": "a quote" }
      ]
    }
  } } }
}`

func TestParseArticlePlainText(t *testing.T) {
	tw := parseTweetResult(decode([]byte(sampleArticleTweet)))
	if tw == nil {
		t.Fatal("parseTweetResult returned nil")
	}
	if tw.ID != "456" {
		t.Errorf("id = %q, want 456", tw.ID)
	}
	if tw.ArticleTitle != "My Great Article" {
		t.Errorf("articleTitle = %q", tw.ArticleTitle)
	}
	want := "Intro\nFirst paragraph.\nstep one\nstep two\na bullet\na quote"
	if tw.ArticleText != want {
		t.Errorf("articleText (plain) =\n%q\nwant\n%q", tw.ArticleText, want)
	}
}

func TestRenderArticleMarkdown(t *testing.T) {
	res := asMap(deepGet(decode([]byte(sampleArticleTweet)), "article", "article_results", "result"))
	cs := articleContentState(res)
	got := renderArticle(asSlice(cs["blocks"]), nil, nil, true)
	want := "# Intro\n\nFirst paragraph.\n\n1. step one\n\n2. step two\n\n- a bullet\n\n> a quote"
	if got != want {
		t.Errorf("markdown =\n%q\nwant\n%q", got, want)
	}
}

// content_state is sometimes delivered as a JSON-encoded string; ensure we
// decode that form too.
func TestArticleContentStateAsString(t *testing.T) {
	res := map[string]any{
		"content_state": `{"blocks":[{"type":"unstyled","text":"hi"}]}`,
	}
	cs := articleContentState(res)
	if cs == nil {
		t.Fatal("expected decoded content_state, got nil")
	}
	if got := renderArticle(asSlice(cs["blocks"]), nil, nil, false); got != "hi" {
		t.Errorf("text = %q, want hi", got)
	}
}

// A tweet with no article block must leave the article fields empty.
func TestNonArticleTweetHasNoArticleFields(t *testing.T) {
	tw := parseTweetResult(decode([]byte(`{
		"rest_id": "1", "legacy": { "full_text": "plain tweet" }
	}`)))
	if tw == nil {
		t.Fatal("nil tweet")
	}
	if tw.ArticleTitle != "" || tw.ArticleText != "" {
		t.Errorf("expected empty article fields, got title=%q text=%q", tw.ArticleTitle, tw.ArticleText)
	}
}
```

## File: pkg/xclient/bookmarkfolders.go
size: 2525
sha: a961d22fe7d3dd79348732cdfdb56f390daf805c
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/bookmarkfolders.go

```text
package xclient

import (
	"context"

	"github.com/dezxbt/agentx/pkg/models"
	"github.com/dezxbt/agentx/pkg/xerrors"
)

// BookmarkFolder is a named bookmark collection.
type BookmarkFolder struct {
	ID   string `json:"id"`
	Name string `json:"name"`
}

// BookmarkFolders lists the account's bookmark folders.
func (c *Client) BookmarkFolders(ctx context.Context) ([]BookmarkFolder, error) {
	data, err := c.graphqlGET(ctx, "BookmarkFoldersSlice", map[string]any{}, nil, nil)
	if err != nil {
		return nil, err
	}
	var out []BookmarkFolder
	for _, raw := range asSlice(deepGet(decode(data), "viewer", "bookmark_collections_slice", "items")) {
		m := asMap(raw)
		if id := asString(m["id"]); id != "" {
			out = append(out, BookmarkFolder{ID: id, Name: asString(m["name"])})
		}
	}
	return out, nil
}

// CreateBookmarkFolder creates a new bookmark folder and returns it.
func (c *Client) CreateBookmarkFolder(ctx context.Context, name string) (*BookmarkFolder, error) {
	data, err := c.graphqlPOST(ctx, "createBookmarkFolder", map[string]any{"name": name}, nil, true)
	if err != nil {
		return nil, err
	}
	m := asMap(deepGet(decode(data), "bookmark_collection_create"))
	id := asString(m["id"])
	if id == "" {
		id = asString(findKey(decode(data), "id"))
	}
	if id == "" {
		return nil, xerrors.New(xerrors.APIError, "bookmark folder not created: unexpected response")
	}
	n := asString(m["name"])
	if n == "" {
		n = name
	}
	return &BookmarkFolder{ID: id, Name: n}, nil
}

// DeleteBookmarkFolder deletes a bookmark folder by id.
func (c *Client) DeleteBookmarkFolder(ctx context.Context, folderID string) error {
	return c.simpleWrite(ctx, "DeleteBookmarkFolder", map[string]any{"bookmark_collection_id": folderID})
}

// BookmarkToFolder bookmarks a tweet into a specific folder.
func (c *Client) BookmarkToFolder(ctx context.Context, tweetID, folderID string) error {
	return c.simpleWrite(ctx, "bookmarkTweetToFolder", map[string]any{
		"tweet_id":               tweetID,
		"bookmark_collection_id": folderID,
	})
}

// BookmarkFolderTweets returns the tweets saved in a bookmark folder.
func (c *Client) BookmarkFolderTweets(ctx context.Context, folderID string, count int, cursor string) (*models.Page, error) {
	vars := map[string]any{
		"bookmark_collection_id": folderID,
		"count":                  clampCount(count),
	}
	if cursor != "" {
		vars["cursor"] = cursor
	}
	data, err := c.graphqlGET(ctx, "BookmarkFolderTimeline", vars, nil, nil)
	if err != nil {
		return nil, err
	}
	return pageFrom(data), nil
}
```

## File: pkg/xclient/client.go
size: 16544
sha: 604319e9276dda3f9d98ddc9e05f1a4a41f67e74
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/client.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/client.go

## File: pkg/xclient/community.go
size: 5273
sha: e2814a4e02f2601e5134d9b77653964def0df26d
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/community.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/community.go

## File: pkg/xclient/constants.go
size: 7077
sha: 75622d20148c4fd9057c86cbd44cb687464041be
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/constants.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/constants.go

## File: pkg/xclient/dm.go
size: 5432
sha: b5ce6d3f869d6b5d97b89b510b75dc5d751d83c6
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/dm.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/dm.go

## File: pkg/xclient/dm_test.go
size: 1090
sha: 4f7277d0bfea75f2c7275ae607ae5a9e3d44b4e2
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/dm_test.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/dm_test.go

## File: pkg/xclient/drafts.go
size: 1797
sha: 3c671a90c26ce5260c34b6d80ae0557e8b2a988e
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/drafts.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/drafts.go

## File: pkg/xclient/grok.go
size: 5157
sha: 0eabeb6ccd79f64ae245afe4094fef8c8b05f37b
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/grok.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/grok.go

## File: pkg/xclient/jsonutil.go
size: 1507
sha: b83af3cd921fb28046baea3262cb773c1905d138
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/jsonutil.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/jsonutil.go

## File: pkg/xclient/lists.go
size: 2593
sha: a969fce8a03837afa907ff628fd88f41d4d2754e
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/lists.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/lists.go

## File: pkg/xclient/login.go
size: 9069
sha: 4ca58c0932383f4ce78f90b62d115166aa808761
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/login.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/login.go

## File: pkg/xclient/notifications.go
size: 4634
sha: c36203414e47e4a65af03afd54a8afd26d359bf5
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/notifications.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/notifications.go

## File: pkg/xclient/oauth.go
size: 6544
sha: a4b2a73f9bc8ed6ee975657910d94e703082cf68
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/oauth.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/oauth.go

## File: pkg/xclient/parser.go
size: 18637
sha: 20bc6fd7f9ea7684c214f6468321f76c715309b2
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/parser.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/parser.go

## File: pkg/xclient/parser_test.go
size: 4234
sha: 1a532ce0b084322eabcc75d26f2d8024637b56ff
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/parser_test.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/parser_test.go

## File: pkg/xclient/poll_reply_test.go
size: 4918
sha: 01395c458b3ac24f22f170d67f22821bb29d3cb0
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/poll_reply_test.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/poll_reply_test.go

## File: pkg/xclient/polls.go
size: 3447
sha: 1866714da0d31f9007af5fde3cd7c02e609afbdb
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/polls.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/polls.go

## File: pkg/xclient/profile.go
size: 901
sha: b9e221c1f0b4b43ac267148ddb848902f4aeb5d7
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/profile.go

```text
package xclient

import (
	"context"
	"net/url"
)

// ProfileFields are the editable profile attributes. Empty fields are omitted,
// so callers can update just the ones they pass.
type ProfileFields struct {
	Name        string // display name
	Description string // bio
	Location    string
	URL         string
}

// UpdateProfile edits the authenticated account's profile (name, bio, location,
// url) via the v1.1 account/update_profile endpoint. Only the non-empty fields
// are sent.
func (c *Client) UpdateProfile(ctx context.Context, f ProfileFields) error {
	form := url.Values{}
	if f.Name != "" {
		form.Set("name", f.Name)
	}
	if f.Description != "" {
		form.Set("description", f.Description)
	}
	if f.Location != "" {
		form.Set("location", f.Location)
	}
	if f.URL != "" {
		form.Set("url", f.URL)
	}
	_, err := c.restPostForm(ctx, "/1.1/account/update_profile.json", form)
	return err
}
```

## File: pkg/xclient/reads.go
size: 14568
sha: 7744dcec93a0b0f729003cb23d9f739585c0e88f
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/reads.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/reads.go

## File: pkg/xclient/restparse.go
size: 2439
sha: 2c3fb8b231f98498f7bded15d2d2c5adf14211b1
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/restparse.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/restparse.go

## File: pkg/xclient/restparse_test.go
size: 1095
sha: 582b6c84f1a7823352e2c8404f11796ba45a3996
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/restparse_test.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/restparse_test.go

## File: pkg/xclient/scheduled.go
size: 2563
sha: a3a937a10a1d0e43aa59e82516036cc04a4a818e
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/scheduled.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/scheduled.go

## File: pkg/xclient/settings.go
size: 4247
sha: 0c3824697ce71e8e2a8ac157ca0c661d09e6966b
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/settings.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/settings.go

## File: pkg/xclient/upload.go
size: 5725
sha: 281ba693b9c79c21c9468584a13686ce66e6c335
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/upload.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/upload.go

## File: pkg/xclient/upload_test.go
size: 409
sha: 28929065703230d3c0e77b31ba708f4587bc2837
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/upload_test.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/upload_test.go

## File: pkg/xclient/utls.go
size: 3912
sha: b0b9e4c0f15071bff3d44f81c02fe11bde48b671
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/utls.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/utls.go

## File: pkg/xclient/writes.go
size: 7734
sha: bfa86415874d28f4ad75cd5010ccf430721abb4f
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/writes.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xclient/writes.go

## File: pkg/xerrors/xerrors.go
size: 1477
sha: 7e455c41707d17381d8bd97ebc3775b59d3cfea9
upstream: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xerrors/xerrors.go

Content is not inlined in the catalog. Read the upstream file: https://github.com/dezxbt/agentx/blob/HEAD/pkg/xerrors/xerrors.go
