twitter

Files (35)

• SKILL.md
• account-stop.yaml · fixtures/
• composes-in-graph.yaml · fixtures/
• continue-saved-plan.yaml · fixtures/
• archive-follower.js · fixtures/data/
• archive-following.js · fixtures/data/
• archive-tweets.js · fixtures/data/
• default-requires-twitter-binding.yaml · fixtures/
• execute-digest-mismatch-refuses.yaml · fixtures/
• execute-missing-plan.yaml · fixtures/
• execute-post-publishes-and-reads-back.yaml · fixtures/
• execute-refused-plan-noop.yaml · fixtures/
• execute-unfollow-batch-stops-at-rate-limit.yaml · fixtures/
• failure-continuation.yaml · fixtures/
• plan-missing-evidence-needs-input.yaml · fixtures/
• plan-prune-ready.yaml · fixtures/
• read-archive-audit.yaml · fixtures/
• read-own-posts-pages.yaml · fixtures/
• recent-empty.yaml · fixtures/
• select-nonmutual-ready.yaml · fixtures/
• select-retweets-ready.yaml · fixtures/
• status-missing-plan.yaml · fixtures/
• account-stop.graph · fixtures/support/
• composed.graph · fixtures/support/
• continuation.graph · fixtures/support/
• failure-continuation.graph · fixtures/support/
• catalog.md · references/
• run.yaml
• twitter-execution-batch.mjs
• twitter-execution-result.mjs
• twitter-execution-values.mjs
• twitter-execution.mjs
• twitter-memory.mjs
• twitter-read.mjs
• twitter-selection.mjs

SKILL.md (first lines)

# Twitter

One account, three lanes: read evidence, plan typed acts, execute an approved
plan.

This is the public branded X (Twitter) catalog skill for the `message-send` action
family. Its core invariant: the agent may read, audit, draft, and plan freely,
but every act that publishes to a public timeline or mutates the account stops
at a human approval gate, and the sealed receipt proves which acts ran, against
which plan digest, with which provider evidence.

Write for the operator who owns the account, the reviewer who approves a live
act, and downstream skills that consume the resulting packets. Keep each plan
to the smallest evidence-backed act set that satisfies the objective. Existing
post and user ids must come from supplied evidence, never memory or guesswork;
name missing evidence as a blocker.

## What this skill does

Seven runners:

- `read`: collect account evidence from the live API through the `twitter`
  connector. Queries: `snapshot`, `posts`, `mentions`, `search`, `following`,
  `followers`. A query without `params.user_id` reads the authenticated
  account; with it, another account. The connector reads whole pages until it
  has at least `max_items`, keeps every item of them, and reports in
  `next_cursor` where a further read starts (pass it back as
  `params.pagination_token`). Emits `runx/twitter.evidence.v1`.
  Read-only; no gate.
- `read-archive`: inspect one contained X archive export (`tweets.js`,
  `following.js`, or `follower.js`) through the runtime's digest-bound artifact
  page seam. Twitter code receives bounded, record-complete pages and never a
  path or whole-file escape hatch. The runtime snapshots up to 512 MiB and this
  skill requests 512 KiB pages; the page size is not a total archive limit.
  Emits the same `runx/twitter.evidence.v1` packet; no gate.
- `plan`: turn one bounded objective plus evidence into `runx/twitter.plan.v1`, an
  explicit list of typed acts with rationale, using agent judgment, then bind
  the exact plan through native `data.digest`. This is the curated lane, for
  dozens of acts that each deserve a reason. A plan is a draft; it delivers
  nothing. The result exposes `twitter_plan.data` and the matching
  `digest_result.data.digest` required by `execute`; callers never calculate
  the digest themselves.
- `select`: the bulk lane. Apply a deterministic predicate to an archive export
  and emit a compact plan, no agent judgment. Use it when the criterion is
  mechanical and the match set runs to thousands, where a per-item rationale
  would be wrong and would exceed the runtime output limit. Two targets:
  `posts` pages `tweets.js` and emits `delete_post` acts (predicate: author,
  date range, engagement threshold), with identical results across page sizes;
  `users` reads a bounded `following.js` bundle and emits
  `unfollow` acts (predicate: `non_mutual: true` for accounts you follow that
  do not follow back, needing `follower.js` too, or an explicit `user_ids`
  list). Emits `runx/twitter.selection.v1` carrying a digest-bound `twitter_plan`.
- `execute`: run the next batch of an approved plan as one `twitter` connector
  operation behind its own approval, sealing per-act outcomes into
  `runx/twitter.execution.v1` and appending one compact progress fact to a durable
  execution ledger. A batch is one published act (a post, reply, quote, or one
  thread segment), or the contiguous run of up to 50 acts of one other kind
  from the cursor. The approval binds that exact call. The kernel records each
  act's outcome as it lands and stops sending at a rate limit, so a monotonic
  cursor, not an accumulated id list, is enough to resume safely.

### Durable operation memory and continuation

The skill remembers an operation in its bound `store`, local to the workspace
by default. It saves the exact plan once under its native digest, separately
from the compact execution progress stream. The saved plan preserves the
objective, account principal, exact content and targets, rationale, evidence
references and any applied context bindings. Progress preserves the pinned
account id, next act, partial thread cursor, cumulative processed, succeeded and failed act counts, a bounded last failure
evidence reference, the last batch summary and structured stop advice. No host opens the store database, reconstructs
completed ids or calculates plan hashes.

On the first `execute`, supply `plan_json` and its native `plan_digest` from
`plan` or `select`. A valid plan is saved before the effect approval; saving it
is not approval. On later calls, omit `plan_json` and supply only the digest.
The skill reads its own progress, selects the next batch and derives the
expected stream version and canonical retry key. The logical store defaults to
`local://twitter`; pass `data_source_uri` when the operation uses another
binding, and keep using that same workspace and store.

- `status` reads one plan and its progress without contacting X. It returns the
  objective, principal, current cursor, partial thread, last batch, next batch
  summary, cumulative outcome counts, failure evidence, structured `stop`,
  `retry_at`, and compact `next_input` for `execute`. It never returns
  an approval or claims a proposed batch has run. `needs_plan` means this store
  has no saved plan: provide the original exact plan once, rather than
  inventing it or resetting a progress stream.
- `recent` lists a bounded page of prior execution summaries and plan digests.
  It does not scan history or return every post. A plan saved at an approval
  pause has no completed batch yet; find that paused invocation through native
  run history and resume its run id.

Each execution reads the bound account. It runs only when that account matches
the plan's principal (`account:@handle`, case insensitive) and, once progress
has pinned an account id, that same account. The exact approval identifies the
verified handle, account id, target and payload. Another available account is
never a fallback.

A native invocation and a multi-batch plan have different identities. If the
invocation pauses, continue **that run id** through `runx resume`; do not start
another run to escape an approval. If a call is interrupted or its outcome is
unknown, read native history and reconcile that same invocation first. Runx
owns in-flight custody and whether an effect may be retried. Only after a batch
is sealed and its result understood should another `execute` start the next
batch. A saved plan, status, receipt or supplied approval reference is context,
never new authority. Relay only actual operator decisions bound to the exact
native request.

Threads advance one segment per batch. The saved cursor contains the next
segment and confirmed reply id, so continuation does not repost earlier
segments. The cursor counts processed acts. Only provider-confirmed successful acts
increment `counts.succeeded`; settled refusals increment `counts.failed`. A
partially published thread is not a completed act. Failures remain visible
across later batches through cumulative counts and a bounded `last_failure`
containing the act, reason and native evidence reference. At the end, execution
returns `completed_with_failures` and status returns `complete_with_failures`
when any terminal act failed. Detailed outcomes remain in native evidence. A refused plan, digest mismatch or already-complete plan does not
append a fake progress event.

From runxhq/runx, Apache-2.0.

More from runxhq/runx