PostSteward
Docs

AGENT INTEGRATION GUIDE

Publish reviewed intent without losing the evidence boundary.

Free includes real direct publishing and explicit scheduling. Advanced adds continuing operation around reviewed sources. Payment, provider configuration and deployment availability remain separate from posting authority.

RuntimeLoading…

1. Connect the owner, then delegate the agent.

The owner signs in through /auth/login, connects an explicit social destination in the workspace and creates a project binding. Standard provider OAuth is implemented for X, Threads and LinkedIn, but each provider button is available only when the deployed provider application and negotiated capabilities are actually configured.

Manual token import remains a fallback for already-authorised user credentials. For X manual import, the owner must explicitly confirm use of their own funded developer application. OAuth-managed credentials and refresh material stay encrypted server-side.

Private GitHub source access uses a separate selected-repository GitHub App path with read-only Contents authority. It is optional and does not itself grant an agent publication permission.

Delegate the smallest useful grant

The owner issues a scoped, expiring agent token. A typical publishing agent needs read, campaign:write, publish and optionally schedule. Add automation or billing only when those operations are intended. Admin authority is not delegable through the grant endpoint.

Store the token once.

New agent secrets are shown once. Put them in the agent's secret manager; do not paste provider credentials or agent tokens into ordinary content or source material.

Prepare original release copy before publication

The owner connects their workspace’s own OpenAI API account in Release preparation. That account pays for generation directly; a ChatGPT subscription is separate. Agents receive no key and need campaign-writing scope plus explicit owner spending consent.

Inspect release evidence, suggested strategy, original drafts and model-assisted checks. Edit or regenerate individual parts; uncertain calls are never retried automatically. Only the owner can approve the exact saved revision and digest. Approval creates immutable copy; publication remains a separate explicit action.

When publishing runs locally, download the approved export and review poststeward preparation import on the paired machine before explicit local scheduling. Read the local handoff commands or the complete preparation contract.

2. Resolve destinations before creating consequential work.

Use accounts_list and projects_list to resolve the exact destination. Then store the approved text in a campaign and validate it before publishing or scheduling.

{
  "project": "product",
  "text": { "product_x": "The exact approved update." },
  "idempotencyKey": "campaign-2026-001"
}

Campaign creation freezes provider-specific text parts and SHA-256 digests. X and Threads copy that exceeds one post is split deterministically into an ordered reply chain; LinkedIn remains a single post. Call campaign_validate with the returned campaign ID. Then call publish_now or schedule_create. HTTP operations are available at POST /api/operations/{name}; remote MCP maps to the same operation catalogue and authority checks.

{
  "campaign": "RETURNED_CAMPAIGN_ID",
  "at": "2026-10-01T12:00:00Z",
  "timezone": "UTC",
  "idempotencyKey": "schedule-2026-001"
}

An agent-created delivery starts at pending_approval. The signed-in owner must inspect the frozen account, stable identity, parts and time and call delivery_approve or delivery_reject. Approval does not replace the agent grant: dispatch rechecks that original authority, so revocation still blocks the effect.

Every consequential mutation carries an idempotency key. Reuse the same key only for the same reviewed inputs when recovering transport delivery. A fresh key is not a safe way to repair an uncertain provider effect.

3. Treat the receipt, not the request, as the record of what happened.

PostSteward separates reservation, provider creation evidence and independent readback. A network timeout after the provider write boundary becomes an ambiguous effect and is fenced against blind repetition.

State Meaning
pending_approval Agent-created work is frozen and cannot reach a provider until owner review.
scheduled Durable approved future reservation; no provider publication claimed.
waiting_container Threads container exists; publication readiness is still pending.
executing Dispatch owns the durable execution claim.
published_verified Recorded provider ID, stable author and exact copy were read back.
published_unverified Creation evidence exists but exact independent readback is not established.
partial_effect One or more multipart IDs are durable, but the chain stopped; completed parts are never replayed.
ambiguous_effect The provider may have accepted the write; blind retry is blocked.
drift_blocked Captured identity, authority or payload no longer matches the reviewed work.
failed A known rejection or pre-effect failure occurred.
cancelled An unclaimed reservation was cancelled.

Use receipt_get, receipts_list and, where creation evidence exists, receipt_recheck. Metrics are separate provider evidence and may be unavailable; unavailable data is not converted to a fabricated zero.

4. Advanced continues reviewed work; it does not invent authority.

Advanced uses a configured GBP monthly workspace price when the deployed rollout policy enables it. The runtime master switch and canary decision remain fail-closed. Payment alone never enables a profile or grants a posting scope.

An automation profile binds a reviewed repository path, explicit project/destination, deterministic template, family, polling interval and minimum spacing. Source text is treated as data, not instructions. Profiles begin paused and require explicit enablement.

Public repositories can be observed anonymously. Selected private repositories can use the owner-authorised GitHub App path. Source monitoring, allocation and metrics are bounded and stop when the relevant entitlement or authority expires.

Runtime availability is authoritative.

The presence of Advanced, X or LinkedIn implementation in the repository is not evidence that a given deployment has enabled the feature. Inspect /readiness.json and /help.json.

5. Recovery restores state, then reconciles external reality.

Exact recovery checkpoints are the primary recovery path. Preparing a recovery quarantines new publication. Restore does not erase posts that may already exist at a provider, so the owner must reconcile restored state and unresolved external-effect evidence before resuming.

  1. Capture or choose an exact checkpoint.
  2. Prepare the recovery plan; publication is quarantined.
  3. Execute the exact restore with the typed owner confirmation.
  4. Reconcile the restarted workspace against current evidence.
  5. Resume only after safety checks pass, or use the exact undo path while it is available.

Approximate timestamp-to-bookmark recovery is a compatibility path and can be unavailable even when exact checkpoints are healthy.

6. Respect provider, workspace and admission limits.

A 429 means admission was rejected; honour Retry-After. Workspaces also have bounded delivery/schedule and storage limits. Provider API charges are separate from PostSteward's service price. Disconnecting an account, revoking a grant or pausing publishing blocks future unclaimed effects but cannot undo a provider effect already started.

Owners can export workspace data, prune eligible old records and request workspace erasure from the Data surface. Recovery and deletion are owner-only transitions with explicit confirmation and durable fences.

For exact operation inputs and the current deployment's enabled capabilities, use the operation reference, help.json and OpenAPI.