platforms/cocottetech
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
cocottetech/@platform/codebase/@features/ai-copilot/docs/provider-ai-actions.contract.md
autocommit 9e9e64351c docs(ai-copilot): 📝 Add comprehensive documentation for AI copilot provider actions, context, entrypoints, and interaction modes 
Co-Authored-By: Lilith Autocommit <noreply@atlilith.com>
2026-05-18 19:58:47 -07:00

14 KiB
Raw Blame History

provider-ai-actions — full action surface

Phase: P0 (categories marked by availability phase) Org scope (per W §W4, forward-compat for P5+): personal → org-scoped in P5

Every action the AI can take on behalf of the provider. Organized by surface. For each category: the upstream skill location, arguments the AI must collect, confirmation policy, the platform.api endpoint, and what state changes.

"Confirmation policy" refers to the approval-card stakes system (see 00-system-visual-system.md §F1 for color + friction mapping). Low-stakes actions may auto-execute on standing instruction; high-stakes always surface an approval card.

Client Area (P0)

v2 analogs: add_client, list_clients, send_quote, mark_paid, add_income_session from quinn.my MCP.

Action Skill Args collected Confirmation Endpoint State change
Invite client platform-clients/actions/invite-client client alias, contact channel, optional rates tier Low — auto if alias + channel provided POST /v1/clients New clients row; welcome message enqueued via notifier
Compose quote platform-clients/actions/compose-quote client_id, session type, duration, rate, incall/outcall Medium — diff card POST /v1/quotes Draft quotes row; status=draft
Finalize + send quote platform-clients/actions/send-quote quote_id (from compose) Medium — approval card PUT /v1/quotes/:id/send status=sent; delivery via notifier
Record client response platform-clients/actions/record-response quote_id, response (accepted/declined/countered), notes Low — auto PUT /v1/quotes/:id/response status updated; if accepted → bookings row created (P3+)
Send invoice platform-clients/actions/send-invoice client_id, amount, description, due_date High — always confirm POST /v1/invoices invoices row created; delivery via notifier
Mark paid platform-clients/actions/mark-paid invoice_id, amount_received, channel (cash/wire/app) Low — auto PUT /v1/invoices/:id/paid status=paid; income session auto-created
Deactivate client platform-clients/actions/deactivate client_id, reason (optional) High — always confirm PUT /v1/clients/:id/deactivate active=false; future bookings blocked

Outreach (P0–P1)

v2 analogs: draft_message, schedule_send, add_prospect, correction-pattern tools from quinn-prospector MCP.

Action Skill Args collected Confirmation Endpoint State change
Draft message platform-outreach/actions/draft-message prospect_id or contact info, channel, intent (warm/intro/follow-up) Low — auto-draft; medium to send POST /v1/outreach/drafts agent_actions row; draft surfaced as approval card
Schedule send platform-outreach/actions/schedule-send draft_id, send_at Low if ≤24h out; medium if >24h PUT /v1/outreach/drafts/:id/schedule draft status=scheduled; notifier worker picks up
Follow-up timer platform-outreach/actions/set-followup prospect_id, delay (hours/days), trigger condition Low POST /v1/outreach/followups Scheduled rule created; fires via scheduler-worker
Mark ghosted platform-outreach/actions/mark-ghosted prospect_id, channel Low — auto PUT /v1/prospects/:id/stage stage=ghosted; triage posture updated
Escalate to alternate channel platform-outreach/actions/escalate-channel prospect_id, from_channel, to_channel Medium — approval card POST /v1/outreach/channel-escalation New outreach record; audit row with escalation rationale

Calendar (P0)

v2 analogs: add_event, find_event_by_slug, manual ICS import.

Action Skill Args collected Confirmation Endpoint State change
Add event platform-calendar/actions/add-event title, start, end, location, linked_tour_stop_id (optional) Low POST /v1/events events row
Modify event platform-calendar/actions/modify-event event_id, changed fields Low if future; medium if ≤24h PUT /v1/events/:id Updated events row; cache.invalidate fired
Cancel event platform-calendar/actions/cancel-event event_id, reason High if client linked; low if internal DELETE /v1/events/:id status=cancelled; if client linked → notifier sends cancellation
Sync from external (iCloud) platform-calendar/actions/sync-external (no args; reads provider's linked iCloud via @mac-sync) Low — auto on schedule POST /v1/calendar/sync Delta import; new/changed rows upserted
Suggest blocking time platform-calendar/actions/suggest-block purpose, duration, preferred time-of-day Low — proposal card POST /v1/events (on confirm) Proposed events row surfaced as card; writes only on approve

Tour Planning (P0)

v2 analogs: create_tour_stop, add_hotel_stay, list_tour_stops, update_tour_stop from quinn.my MCP + add_to_tour_schedule Tryst tool.

Action Skill Args collected Confirmation Endpoint State change
Create tour stop platform-tours/actions/create-stop city, start_date, end_date, surface_publish targets (default all active N2) Medium — multi-surface fanout card POST /v1/tours/stops tour_stops row; dispatch to bookings-* specialists
Modify tour stop platform-tours/actions/modify-stop stop_id, changed fields, re-publish flag Medium PUT /v1/tours/stops/:id Updated row; conditional re-publish
Evaluate viability platform-tours/actions/evaluate-viability city, dates Low — proposal only (read-only analysis; no write) Returns viability card (demand signals, hotel availability, booking lead-time)
Find hotel candidates platform-tours/actions/find-hotels city, dates, preference profile (from context) Low — proposal card GET /v1/hotels/search No write; candidates surfaced; provider selects; add-hotel-stay follows
Add hotel stay platform-tours/actions/add-hotel-stay stop_id, hotel name, check_in, check_out, confirmation_number (optional) Low POST /v1/hotels/stays hotel_stays row linked to stop

Finance (P0)

v2 analogs: add_income_session, add_purchase, add_subscription from quinn.my MCP.

Action Skill Args collected Confirmation Endpoint State change
Record income session platform-finance/actions/record-income client_id (optional), amount, date, session type, duration Low POST /v1/finance/income income_sessions row
Log purchase platform-finance/actions/log-purchase description, amount, date, category Low POST /v1/finance/purchases purchases row
Add subscription platform-finance/actions/add-subscription service name, amount, billing cycle, next_billing_date Low POST /v1/finance/subscriptions subscriptions row
Generate invoice draft platform-finance/actions/generate-invoice client_id, line items, due_date Medium — diff card POST /v1/invoices (status=draft) Draft invoices row surfaced for review
Reconcile against statement platform-finance/actions/reconcile statement upload (PDF/CSV via multimodal input) Medium — review card POST /v1/finance/reconcile Matches against existing records; unmatched rows surfaced for provider decision

Content (P1)

v2 analogs: add_platform_ad_copy, add_photo_to_gallery, cross-surface fanout patterns from v2 admin.

Action Skill Args collected Confirmation Endpoint State change
Draft platform ad copy platform-content/actions/draft-ad-copy surface, intent changes (or "refresh"), persona facet for that surface Medium — diff card PUT /v1/ad-copy/:surface Draft ad copy stored; published on approve
Request photo regeneration platform-content/actions/request-regen asset_id, style prompt delta Medium — preview card POST /v1/content/regen-request Request enqueued to @ml; result returned async, surfaced as approval card
Schedule cross-surface fanout platform-content/actions/schedule-fanout logical change (text, rates, photo), audience selector (see cross-surface-fanout.brief.md §2a) Medium to High (per §6 stakes inheritance) POST /v1/content/fanout agent_actions parent row; per-surface dispatch to owning content-* + bookings-* specialists
Add to gallery platform-content/actions/add-to-gallery asset (photo drop via multimodal), tags, surface restrictions Low POST /v1/content/assets content_assets row; available to specialist drafters

Inbox (P0)

v2 analogs: triage 5-check chain from v2 coworker-agent + triage specialist.

Action Skill Args collected Confirmation Endpoint State change
Triage thread platform-inbox/actions/triage (automatic — driven by triage specialist on inbound) None for auto-route; medium for escalate-to-provider PUT /v1/inbox/threads/:id/triage Thread tagged with triage result; routed to drafts queue or escalated
Draft reply platform-inbox/actions/draft-reply thread_id, intent (close/warm/schedule) Low auto-draft; medium to send POST /v1/inbox/drafts Draft surfaced as approval card
Schedule send platform-inbox/actions/schedule-send draft_id, send_at Low PUT /v1/inbox/drafts/:id/schedule Draft status=scheduled
Mark archive platform-inbox/actions/archive thread_id Low — auto on triage decision PUT /v1/inbox/threads/:id/archive Thread removed from active inbox; preserved in audit
Escalate platform-inbox/actions/escalate thread_id, reason Low (system decision to escalate) PUT /v1/inbox/threads/:id/escalate Thread surfaced as high-priority approval card; triage posture noted

Prospect Funnel (P0–P4)

v2 analogs: add_prospect, prospect funnel stage tooling, quinn-prospector correction patterns.

Action Skill Args collected Confirmation Endpoint State change
Tag prospect platform-prospects/actions/tag prospect_id, tag value Low PUT /v1/prospects/:id/tags Tag added to prospects row
Change funnel stage platform-prospects/actions/set-stage prospect_id, stage (cold/warm/hot/booked/ghosted/blocked) Low for cold/warm/hot; medium for blocked PUT /v1/prospects/:id/stage Stage updated; triage posture may cascade
Apply correction pattern platform-prospects/actions/apply-correction prospect_id, correction description Low POST /v1/prospects/corrections (stored in quinn-prospector MCP) Correction pattern stored; future triage re-evaluated
Record decision platform-prospects/actions/record-decision prospect_id, decision, rationale Low POST /v1/prospects/decisions agent_actions row; informs correction learning

Knowledge / Memory (P0)

v2 analogs: add_journal_entry, add_observation, add_inspiration from quinn.my MCP.

Action Skill Args collected Confirmation Endpoint State change
Add journal entry platform-knowledge/actions/add-journal title (optional), body, tags Low POST /v1/journal journal_entries row
Record observation platform-knowledge/actions/add-observation subject (prospect/client/surface/hotel), body Low POST /v1/observations Observation row linked to subject entity
Add inspiration platform-knowledge/actions/add-inspiration body, tags (content/outreach/positioning) Low POST /v1/inspirations Inspiration row; surfaced to strategist on next content-plan run
Query history platform-knowledge/actions/query natural-language question Low — read only GET /v1/knowledge/search No write; RAG retrieval via @ml/knowledge-platform; surfaced in chat

Self (AI-internal actions)

These actions adjust how the AI operates, not the provider's business data.

Action Skill Args collected Confirmation Endpoint State change
Propose prompt revision platform-ai/actions/propose-prompt revised system prompt fragment, rationale High — always confirm; provider approves PUT /v1/ai/system-prompt AI's persona config updated; correction logged
Request more context (inline AI behavior — no skill call) Clarifying question surfaced in chat None — No write; turn continues after provider replies
Ask clarifying question (inline AI behavior — no skill call) Question surfaced when ambiguity detected None — No write; turn continues
Defer to provider (inline AI behavior — no skill call) Stakes or ambiguity above threshold; escalation card surfaced None — No write; agent_actions row with status=deferred

Open questions

  • Booking confirmation write-back (P3+): when a bookings-tryst action creates a booking, should the AI auto-create a record-income draft pre-filled with Tryst rates, or wait for the provider to trigger it? Decision lives in the bookings-tryst specialist contract (specialist-bookings-tryst.contract.md).
  • Finance reconciliation upload (multimodal): PDF statement parsing is listed here; actual parser lives in @ml. Latency + accuracy SLA not yet defined. Open in OPEN-DECISIONS.md.
  • Content regen async surface: the approval card for a regen request arrives async (model inference takes time). Current assumption: push notification + chat card on completion. Interaction pattern for "still waiting" state not yet designed.

Related