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.
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.
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.