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.
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.
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.
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"
}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"
}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 |
|---|---|
scheduled | Durable 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. |
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 is USD 5 per workspace per month 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.
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.
- Capture or choose an exact checkpoint.
- Prepare the recovery plan; publication is quarantined.
- Execute the exact restore with the typed owner confirmation.
- Reconcile the restarted workspace against current evidence.
- 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.