Extra Chill Roadie

Extra Chill platform integration for Frontend Agent Chat, powered by Data Machine agents. Roadie gives the Extra Chill chat agent the ability to manage artist profiles, link pages, user profiles, and community forums — and, for team members, to file GitHub issues and ship sandboxed code changes — all through natural language chat.

What It Does

Roadie is the bridge between Extra Chill's platform features and Data Machine's chat system. It registers nine chat tools via the datamachine_tools filter and composes a role-aware operating context (the roadie agent mode) into the AI prompt. The tool surface a caller actually sees depends on their tier (public / team / admin).

The four cross-site management tools require authentication (access_level: authenticated) and auto-resolve the artist ID when the user has a single artist profile. The code-contribution and feature-request tools additionally require the extrachill_propose_code capability. search_content and present_question are the two public-access tools and are the only tools visible to public-tier callers — search_content because the published catalog is public (logged-out visitors get grounded, sourced answers too), present_question because it is purely presentational.

Role-Aware Tier Surface

Roadie resolves every caller to one of three tiers and tailors both the visible tool set and the prompt guidance accordingly.

Tier resolution lives in extrachill_roadie_user_tier( int $user_id ) (inc/permissions.php) — a single auditable capability→tier map (highest wins): manage_options → admin, access_roadie → team, otherwise public.

Two enforcement layers back this:

1. Tool visibility — extrachill_roadie_filter_tools_by_tier() hooks datamachine_resolved_tools and, for public-tier callers, unset()s the seven management tools returned by extrachill_roadie_managed_tool_slugs() (everything except the two public tools, search_content and present_question). This avoids offering the model dead options.
2. Per-call gates — independent of visibility: cross-site write capability checks, assert_acting_user_allowed() (admin-only act-on-behalf-of), and current_user_can( 'extrachill_propose_code' ) on the code/issue tools.

Architecture

Roadie follows the Extra Chill platform pattern: business logic lives in domain plugins (extrachill-users, extrachill-api, extrachill-artist-platform, etc.), and Roadie provides the AI-facing tool interface on top.

User (chat) → Data Machine → Roadie Tool → ec_cross_site_rest_request() → Subsite REST API → Ability

ECRoadie_PlatformTool

The four cross-site management tools extend ECRoadie_PlatformTool (inc/tools/class-ec-platform-tool.php), which extends Data Machine's BaseTool and provides:

• rest_request( $method, $path, $args ) — Cross-site REST calls via ec_cross_site_rest_request(). Pass user_id in $args to authenticate the request as that user; the underlying helper wraps wp_set_current_user() in a try/finally so context restores cleanly.
• get_blog_id() — Site key resolution for safe data reads via switch_to_blog().
• get_calling_user_id( $parameters ) — Reads calling_user_id from the merged tool parameters. Data Machine's loop merges the invocation payload into $parameters before calling handle_tool_call(), so the human caller is always available as $parameters['calling_user_id'].
• resolve_acting_user_id( $parameters ) — Returns the user the tool should act as. Priority: explicit user_id input → calling_user_id → get_current_user_id().
• assert_acting_user_allowed( $acting, $parameters ) — Returns a clean permission-denied response (or null when allowed). Non-admin callers attempting to act on another user are refused.

Each tool declares a $site_key (e.g. 'artist', 'community', 'main') and a $tool_slug for error context. The code-contribution, feature-request, and present-question tools extend BaseTool directly (they don't make cross-site REST calls).

Agent Mode

Roadie registers a roadie execution mode with Data Machine's AgentModeRegistry. The mode is the operating context for the EC platform tool surface — it composes EC-specific guidance (network topology, tool selection, identity contract, editorial voice, operating posture) into the AI prompt.

// inc/agent-mode/register.php
add_action( 'datamachine_agent_modes', function () {
    \DataMachine\Engine\AI\AgentModeRegistry::register( 'roadie', 45, array(
        'label'       => __( 'Extra Chill Platform', 'extrachill-roadie' ),
        'description' => __( 'Artist profiles, link pages, user profiles, community forum, and personal user-scoped operations on the EC multisite network.', 'extrachill-roadie' ),
    ) );
} );

add_filter( 'datamachine_agent_mode_roadie', 'extrachill_roadie_mode_guidance', 10, 2 );

The mode is agent-agnostic — any agent (extra-chill-bot, roadie, or a custom one) can run in this mode and inherit the same platform guidance. Priority 45 places it after data-machine-editor (40) so editor mode wins when both are active in the same invocation (rare).

The guidance is role-aware: extrachill_roadie_mode_guidance() resolves the caller's calling_user_id → tier and delegates to extrachill_roadie_compose_guidance( $tier, $uid ), which assembles tier-specific sections (intro, tool guidance, identity contract, operating posture) on top of shared sections (network topology, editorial voice). The composed prompt is titled # Extra Chill Platform Context.

Calling-User Identity Contract

Every Roadie tool sees the human caller via $parameters['calling_user_id']. The chat orchestrator sets this from the chat session caller; pipeline runs and system tasks set it to 0.

The contract for tool wiring:

1. Resolve the acting user once at the top of handle_tool_call():

   $acting_user_id = $this->resolve_acting_user_id( $parameters );
   $denied = $this->assert_acting_user_allowed( $acting_user_id, $parameters );
   if ( null !== $denied ) {
       return $denied;
   }

2. Pass 'user_id' => $acting_user_id into every rest_request() so the cross-site helper switches context correctly.
3. For tools that read user-scoped data directly (e.g. get_user_meta), use $acting_user_id instead of get_current_user_id().
4. Public read actions (e.g. list_forums) can skip the resolve/assert pair entirely.

Admin agents may target another user by passing an explicit user_id input; non-admins attempting that get a clean permission-denied response.

Permissions

Roadie bridges Extra Chill team membership to Data Machine's agent access system:

• Hooks datamachine_can_access_agent to grant EC team members access to the Roadie agent.
• Uses the network-wide access_roadie capability (granted to the extra_chill_team role) as the source of truth.
• Grants extrachill_propose_code to administrators, editors, and extra_chill_team by default (filterable via extrachill_roadie_propose_code_roles).
• Bridges the events read/write capabilities (datamachine_events_read_capability / datamachine_events_write_capability).
• Agent policy (name, status, redirect URIs) is synced on plugins_loaded (priority 20).

Bridge Onboarding

For external chat clients (like Beeper/Matrix via mautrix-data-machine), Roadie provides onboarding configuration via the datamachine_bridge_onboarding_config filter:

• Welcome message, description, login instructions.
• Room name and topic for the chat bridge.
• Consumer-facing capability list (artist profile, link page, user profile, community).
• Avatar URL (filterable via extrachill_roadie_bridge_avatar_url).

The onboarding capability list is intentionally end-user-facing — the team-gated code and issue tools aren't advertised there because a public bridge user would never see them.

Chat Tool Reference

manage_artist_profile

Optional fields for create/update: bio, genre, local_city, profile_image_id (0 to remove), header_image_id (0 to remove).

manage_link_page

Convenience actions (add_link, remove_link) handle the fetch-modify-save cycle internally so the AI doesn't need multi-step orchestration.

manage_user_profile

Profile links support types: website, facebook, instagram, twitter, youtube, tiktok, spotify, soundcloud, bandcamp, github, other. These are the links on the user's community profile — distinct from artist link pages.

manage_community

The first three actions are public reads (no user context); the rest resolve and authorize the acting user.

propose_code_change

Dispatches a sandboxed coding agent (WP Codebox Playground) that implements the described change against the subsite's stack and returns a reviewable patch artifact + live preview URL. It does not push code or open a PR.

Returns status: pending-approval, artifact_id, preview_url, summary, changed_files. Requires the extrachill_propose_code capability. See docs/contribute-code.md for the full flow.

apply_code_change

Applies a previously-approved artifact: creates a worktree per affected repo, applies the patch, commits with a conventional commit message, pushes, and opens a pull request.

Returns pr_urls. Only call after the user has explicitly approved the proposed change. Requires extrachill_propose_code.