{"ok":true,"version":"agent-sessions.v1","generatedAt":"2026-05-30T06:50:59.001Z","surface":{"id":"agent-sessions","artistId":"laurel","safeForAgent":true,"browserAutomationRequired":false,"storageRuntimeReady":false,"relatedIssues":[608,610,674,810,1112,1113,1114,1130,1177]},"currentStatus":{"contract":"manifest-ready","storage":"not-enabled","eventStream":"planned","eventLog":"sample-readback-ready","summary":"This surface defines how Fanful should represent external agent runs, events, approvals, and cancellation. It exposes deterministic sample event-log readback, but does not persist sessions yet."},"whenToUse":{"agentSessions":"Use an agent session when work spans more than one tool call, needs approval tracking, or should be inspectable by a creator, listener, operator, or support UI.","workflowTriggers":"Use workflow triggers to wake an authorized agent from a Fanful event. A triggered agent should attach follow-up work to a session before requesting approvals or writes.","statelessMcp":"Use stateless MCP reads for one-shot answers that do not need durable history, pending approval state, or event replay."},"endpoints":{"manifest":{"href":"https://docs.fanful.net/api/agent/sessions","method":"GET","auth":"guest","description":"Read this contract manifest.","status":"available"},"createSession":{"href":"https://docs.fanful.net/api/agent/sessions","method":"POST","auth":"scoped-agent-grant","description":"Planned endpoint for creating a durable external agent session after scoped authorization.","status":"planned"},"appendMessage":{"href":"https://docs.fanful.net/api/agent/sessions/{sessionId}/messages","method":"POST","auth":"scoped-agent-grant","description":"Planned endpoint for appending a redacted human or agent message summary.","status":"planned"},"readEvents":{"href":"https://docs.fanful.net/api/agent/sessions/{sessionId}/events","method":"GET","auth":"scoped-agent-grant","description":"Read deterministic sample session events with cursor pagination. Durable event storage and streaming remain planned.","status":"available"},"resolveApproval":{"href":"https://docs.fanful.net/api/agent/sessions/{sessionId}/approvals/{approvalId}","method":"PATCH","auth":"first-party-session","description":"Planned endpoint for approving, rejecting, or expiring one pending approval.","status":"planned"},"cancelSession":{"href":"https://docs.fanful.net/api/agent/sessions/{sessionId}/cancel","method":"POST","auth":"first-party-session","description":"Planned endpoint for cancelling a run and recording the cancellation event.","status":"planned"}},"sessionContract":{"contract":"agent-session.v1","requiredFields":["id","status","workflow","principal","client","community","requestedBy","createdAt","updatedAt","pendingApprovals","completedToolCalls","latestEventCursor"],"statuses":["active","waiting-for-approval","completed","cancelled","failed"],"principalPolicy":"Resolve principals server-side from first-party sessions or scoped delegated grants. Never accept bearer tokens, grant ids, Better Auth user ids, or listener database identifiers as model-visible session fields."},"eventContract":{"contract":"agent-session-event.v1","requiredFields":["id","sessionId","sequence","type","occurredAt","actor","summary","correlation","redactions"],"eventTypes":["session.created","message.appended","tool.call.started","tool.call.completed","approval.requested","approval.resolved","session.completed","session.cancelled"],"cursorPolicy":"Events should be replayable by monotonically increasing sequence or opaque cursor. Do not require agents to scrape UI logs.","redactionPolicy":"Events carry summaries, public ids, contract ids, and redacted references. Listener database identifiers, Better Auth ids, Stripe ids, media URLs, invite tokens, provider secrets, private message bodies, and admin credentials stay out of model-visible event payloads."},"eventLogContract":{"contract":"agent-session-events.v1","endpointTemplate":"https://docs.fanful.net/api/agent/sessions/{sessionId}/events","cursorQuery":"cursor","currentStorage":"sample-event-log-only","durableStorage":"planned","streamTransport":"planned","replayRule":"Clients may replay deterministic sample logs today by passing the latest returned cursor. Durable event logs must keep the same redaction and cursor semantics before runtime storage is enabled."},"approvalContract":{"contract":"agent-session-approval.v1","requiredFields":["id","sessionId","contract","targetSummary","confirmationText","status","requestedAt","expiresAt"],"resolutionFields":["resolvedBy","resolvedAt","resolutionReason"],"writeRule":"A pending approval is not executable by itself. The current action-contract manifest and shared agent-write-envelope.v1 must still validate before any write runs."},"migrationPath":["Keep stateless MCP tools as the portable action/read contract.","Attach multi-step or approval-seeking work to a durable agent session.","Use deterministic sample event-log readback to test client parsing before durable storage ships.","Store redacted session events as an auditable history for creators, listeners, operators, and support.","Let workflow triggers create or resume sessions after signed delivery exists.","Expose event readback through MCP resources and first-party UI before adding hosted long-running execution."],"sampleEventLogEndpoints":["https://docs.fanful.net/api/agent/sessions/agent-session-creator-live-0001/events","https://docs.fanful.net/api/agent/sessions/agent-session-listener-support-0001/events"],"sampleSessions":[{"id":"agent-session-creator-live-0001","title":"Prepare a live room schedule update","workflow":"creator.live.schedule-update","status":"waiting-for-approval","principal":{"source":"scoped-agent-grant","role":"creator","artistId":"laurel","communityId":"community_laurel_public","scopes":["creator:laurel:live:read","creator:laurel:live:write"]},"community":{"id":"community_laurel_public","artistId":"laurel","displayName":"Laurel public community","visibility":"public"},"requestedBy":{"kind":"creator","displayName":"Laurel admin"},"client":{"id":"client-codex-agent-experience","name":"Agent Experience","kind":"codex"},"createdAt":"2026-05-16T08:00:00.000Z","updatedAt":"2026-05-16T08:00:20.000Z","pendingApprovals":[{"id":"approval-live-schedule-update-0001","contract":"creator.live.schedule.update","targetSummary":"Move Laurel Studio Room from 7:00 PM to 7:30 PM.","confirmationText":"I confirm updating Laurel Studio Room to 7:30 PM.","expiresAt":"2026-05-16T09:30:00.000Z"}],"completedToolCalls":[{"id":"tool-call-live-readiness-0001","tool":"fanful_live_readiness_read","mode":"read","resultSummary":"Live room exists and is currently scheduled."},{"id":"tool-call-live-schedule-preview-0001","tool":"fanful_live_schedule_preview","mode":"preview","resultSummary":"Schedule update preview returned no blockers and exact confirmation copy."}],"latestEventCursor":"agent-session-creator-live-0001:3","events":[{"id":"run-event-creator-0001","sessionId":"agent-session-creator-live-0001","type":"session.created","occurredAt":"2026-05-16T08:00:00.000Z","sequence":1,"actor":{"kind":"human","displayName":"Laurel admin"},"summary":"Creator authorized a live schedule assistance run.","correlation":{"sessionId":"agent-session-creator-live-0001","auditCorrelationId":"agent-session-audit-live-schedule-0001"},"redactions":["Better Auth user id","grant id","admin email"]},{"id":"run-event-creator-0002","sessionId":"agent-session-creator-live-0001","type":"tool.call.completed","occurredAt":"2026-05-16T08:00:08.000Z","sequence":2,"actor":{"kind":"agent","displayName":"Agent Experience"},"summary":"Read live readiness and schedule state before proposing a write.","target":{"surface":"live-readiness","operation":"fanful_live_readiness_read","contract":"agent-live-readiness.v1"},"correlation":{"sessionId":"agent-session-creator-live-0001","auditCorrelationId":"agent-session-audit-live-schedule-0001"},"redactions":["stream keys","private invite tokens","listener database identifiers"]},{"id":"run-event-creator-0003","sessionId":"agent-session-creator-live-0001","type":"approval.requested","occurredAt":"2026-05-16T08:00:20.000Z","sequence":3,"actor":{"kind":"agent","displayName":"Agent Experience"},"summary":"Requested exact confirmation before executing the schedule update.","target":{"surface":"live-controls","operation":"fanful_creator_live_schedule_update","contract":"creator.live.schedule.update"},"approval":{"id":"approval-live-schedule-update-0001","status":"pending","confirmationText":"I confirm updating Laurel Studio Room to 7:30 PM."},"correlation":{"sessionId":"agent-session-creator-live-0001","auditCorrelationId":"agent-session-audit-live-schedule-0001","idempotencyKey":"agent-session-live-schedule-update-0001"},"redactions":["admin token","raw live provider ids","private media URLs"]}]},{"id":"agent-session-listener-support-0001","title":"Check support checkout readiness","workflow":"listener.support.checkout-preview","status":"completed","principal":{"source":"first-party-session","role":"listener","artistId":"laurel","communityId":"community_laurel_public","scopes":["listener:profile:read","listener:checkout:preview"]},"community":{"id":"community_laurel_public","artistId":"laurel","displayName":"Laurel public community","visibility":"public"},"requestedBy":{"kind":"listener","displayName":"Signed-in listener"},"client":{"id":"client-chatgpt-fanful-preview","name":"Fanful ChatGPT preview","kind":"chatgpt-app"},"createdAt":"2026-05-16T08:05:00.000Z","updatedAt":"2026-05-16T08:05:12.000Z","pendingApprovals":[],"completedToolCalls":[{"id":"tool-call-support-preview-0001","tool":"fanful_listener_live_support_preview","mode":"preview","resultSummary":"Support CTA is available and checkout start still requires explicit listener confirmation."}],"latestEventCursor":"agent-session-listener-support-0001:4","events":[{"id":"run-event-listener-0001","sessionId":"agent-session-listener-support-0001","type":"session.created","occurredAt":"2026-05-16T08:05:00.000Z","sequence":1,"actor":{"kind":"human","displayName":"Signed-in listener"},"summary":"Listener asked whether they can support the current live room.","correlation":{"sessionId":"agent-session-listener-support-0001","auditCorrelationId":"agent-session-audit-support-checkout-0001"},"redactions":["Better Auth user id","listener id","listener email"]},{"id":"run-event-listener-0002","sessionId":"agent-session-listener-support-0001","type":"tool.call.completed","occurredAt":"2026-05-16T08:05:04.000Z","sequence":2,"actor":{"kind":"agent","displayName":"Fanful ChatGPT preview"},"summary":"Read support checkout readiness without starting checkout.","target":{"surface":"listener-experience","operation":"fanful_listener_live_support_preview","contract":"fanful.live-support-readiness.v1"},"correlation":{"sessionId":"agent-session-listener-support-0001","auditCorrelationId":"agent-session-audit-support-checkout-0001"},"redactions":["Stripe ids","listener database identifiers","payment identifiers"]},{"id":"run-event-listener-0003","sessionId":"agent-session-listener-support-0001","type":"message.appended","occurredAt":"2026-05-16T08:05:10.000Z","sequence":3,"actor":{"kind":"agent","displayName":"Fanful ChatGPT preview"},"summary":"Explained that checkout start needs exact listener confirmation.","correlation":{"sessionId":"agent-session-listener-support-0001","auditCorrelationId":"agent-session-audit-support-checkout-0001"},"redactions":["private message body beyond summary","device id","push token"]},{"id":"run-event-listener-0004","sessionId":"agent-session-listener-support-0001","type":"session.completed","occurredAt":"2026-05-16T08:05:12.000Z","sequence":4,"actor":{"kind":"system","displayName":"Fanful agent session ledger"},"summary":"Closed the read-only checkout preview run without starting checkout.","correlation":{"sessionId":"agent-session-listener-support-0001","auditCorrelationId":"agent-session-audit-support-checkout-0001"},"redactions":["listener database identifiers","Stripe ids","private message body beyond summary"]}]}],"agentClientGuidance":["Start a session before asking for a confirmation that may outlive the current chat turn.","Record only redacted event summaries and contract ids in model-visible history.","Use the sample event-log endpoints to validate event replay and cursor handling until durable storage is enabled.","Read current manifests again immediately before any confirmed write.","Cancel a session rather than silently abandoning pending approvals."]}