desktop-mode / includes / agents / bootstrap.php

bootstrap.php in OpenStation: Desktop Windows, Dock & Virtual Desktops for WP Admin 1.1.8, at includes/agents/bootstrap.php

184 lines 6.7 KB

Raw Download Zip

1	<?php
2	/**
3	* OpenStation — Agents module bootstrap.
4	*
5	* Agents are durable workers that live on the site as real WordPress
6	* users and act through the WordPress Abilities API under their own
7	* role and capabilities. Three layers:
8	*
9	* - Guard — the marker meta, the agent test, and every login /
10	* session block → guard.php (ALWAYS loaded)
11	* - Identity — the synthetic `wp_users` row itself → identity.php
12	* - Definition — everything else (system prompt, description, ability
13	* allowlist, triggers, model override, rate limit) as
14	* user meta on that row → store.php
15	*
16	* Plus the abilities bridge + runner (runner.php), a REST surface at
17	* `/desktop-mode/v1/agents` (rest.php), privacy hooks (privacy.php),
18	* the "Agent chat" native window (run-window.php), and the Agents
19	* section inside WP Explorer (my-wordpress.php).
20	*
21	* The module is opt-in behind the `agents` extended option — while
22	* off, no user-meta registration, no REST routes and no chat window.
23	* Guard, WP Explorer discovery, and job cleanup load regardless of the flag.
24	* See below for why.
25	*
26	* @package OpenStation
27	*/
28
29	defined( 'ABSPATH' ) \|\| exit;
30
31	/**
32	* The authentication guard loads unconditionally, ahead of the feature
33	* flag. Disabling the Agents framework does not delete the agent user
34	* rows, and an agent row whose login blocks unloaded with the feature
35	* would accept application passwords and password resets again. The
36	* blocks are a property of the rows, not of the feature.
37	*/
38	require_once OPENSTATION_DIR . 'includes/agents/guard.php';
39
40	// ---------------------------------------------------------------------------
41	// Always-available helpers
42	//
43	// The capability helpers and the avatar URL live here rather than in
44	// rest.php / identity.php because the WP Explorer integration needs
45	// all four to build its entity descriptor, and it now loads while the
46	// feature flag is off — when neither of those files is loaded.
47	// ---------------------------------------------------------------------------
48
49	/**
50	* URL of the bot avatar as a real static file.
51	*
52	* The avatar MUST be a file URL, not the data URI: consumers routinely
53	* run avatar URLs through `esc_url()` (wp-admin's `get_avatar()`, the
54	* desktop user-tile renderer), and `data` is not in
55	* `wp_allowed_protocols()` — the data URI silently becomes an empty
56	* string and the avatar renders broken.
57	*
58	* With an agent id, this is that agent's own Mio portrait when one has
59	* been written. Without one, or before the face file exists, it is the
60	* shipped robot glyph, which is what every agent wore before faces.
61	*
62	* @param int $user_id Agent user id, or 0 for the generic glyph.
63	* @return string
64	*/
65	function openstation_agent_avatar_url( $user_id = 0 ) {
66	// Called with no argument for the generic case: the WP Explorer
67	// section icon, and the fallback for an agent that has no face yet.
68	// A section icon wearing one agent's face would be wrong.
69	if ( $user_id > 0 && function_exists( 'openstation_agent_face_url' ) ) {
70	$face = openstation_agent_face_url( (int) $user_id );
71	if ( '' !== $face ) {
72	return $face;
73	}
74	}
75	return OPENSTATION_URL . 'assets/images/agent-avatar.svg';
76	}
77
78	/**
79	* Whether the current user can see agents.
80	*
81	* @return bool
82	*/
83	function openstation_agents_user_can_read() {
84	/**
85	* Filter whether the current user can read OpenStation agents.
86	*
87	* @param bool $can Default: `edit_posts` capability.
88	*/
89	return (bool) apply_filters( 'openstation_agents_user_can_read', current_user_can( 'edit_posts' ) );
90	}
91
92	/**
93	* Whether the current user can create / edit / delete agents.
94	*
95	* @return bool
96	*/
97	function openstation_agents_user_can_manage() {
98	/**
99	* Filter whether the current user can manage OpenStation agents.
100	*
101	* @param bool $can Default: `edit_users` capability.
102	*/
103	return (bool) apply_filters( 'openstation_agents_user_can_manage', current_user_can( 'edit_users' ) );
104	}
105
106	/**
107	* Whether the current user can invoke agents.
108	*
109	* @return bool
110	*/
111	function openstation_agents_user_can_invoke() {
112	/**
113	* Filter whether the current user can invoke OpenStation agents.
114	*
115	* @param bool $can Default: `edit_posts` capability.
116	*/
117	return (bool) apply_filters( 'openstation_agents_user_can_invoke', current_user_can( 'edit_posts' ) );
118	}
119
120	/**
121	* Whether the Agents framework is enabled site-wide.
122	*
123	* Backed by the `agents` key of the extended options bundle
124	* (`openstation_get_extended_options()`), default off — opt-in.
125	*
126	* @return bool
127	*/
128	function openstation_agents_enabled() {
129	$options = openstation_get_extended_options();
130	$enabled = ! empty( $options['agents'] );
131
132	/**
133	* Filters whether the Agents framework is enabled site-wide.
134	*
135	* Runs on `plugins_loaded` (priority 5) to decide whether the
136	* agents module loads at all, and again at runtime wherever the
137	* enabled state is consulted.
138	*
139	* @param bool $enabled Whether the Agents framework is enabled.
140	*/
141	return (bool) apply_filters( 'openstation_agents_enabled', $enabled );
142	}
143
144	/**
145	* The WP Explorer integration also loads unconditionally, so the Agents
146	* section is always discoverable: a site that has never turned the
147	* framework on still shows the tile, and the section explains how to
148	* switch it on instead of hiding the feature from the one person who
149	* could enable it. Everything inside renders inert while the flag is
150	* off — `openstation_agents_my_wordpress_window_args()` ships
151	* `enabled => false`, and the renderer disables every control and skips
152	* every fetch (the REST routes genuinely do not exist while off).
153	*
154	* Loaded after the helpers above, which it needs to build the entity
155	* descriptor and the section config.
156	*/
157	require_once OPENSTATION_DIR . 'includes/agents/my-wordpress.php';
158	// Queued work must fail safely and retained data must expire even when disabled.
159	require_once OPENSTATION_DIR . 'includes/agents/jobs.php';
160
161	/**
162	* Loads the agents module when the framework is enabled.
163	*
164	* @access private
165	*/
166	function openstation_agents_load() {
167	if ( ! openstation_agents_enabled() ) {
168	return;
169	}
170
171	require_once OPENSTATION_DIR . 'includes/agents/store.php';
172	require_once OPENSTATION_DIR . 'includes/agents/defaults.php';
173	require_once OPENSTATION_DIR . 'includes/agents/identity.php';
174	require_once OPENSTATION_DIR . 'includes/agents/face.php';
175	require_once OPENSTATION_DIR . 'includes/agents/abilities.php';
176	require_once OPENSTATION_DIR . 'includes/agents/runner.php';
177	require_once OPENSTATION_DIR . 'includes/agents/draft.php';
178	require_once OPENSTATION_DIR . 'includes/agents/rest.php';
179	require_once OPENSTATION_DIR . 'includes/agents/conversations.php';
180	require_once OPENSTATION_DIR . 'includes/agents/privacy.php';
181	require_once OPENSTATION_DIR . 'includes/agents/run-window.php';
182	}
183	add_action( 'plugins_loaded', 'openstation_agents_load', 5 );
184