codex_extension_api/
user_instructions.rs

1use std::future::Future;
2use std::pin::Pin;
3
4use codex_utils_absolute_path::AbsolutePathBuf;
5
6/// User instructions supplied by the host.
7///
8/// `source` must be an absolute filesystem path because the app-server
9/// `instructionSources` API currently exposes instruction sources as
10/// `AbsolutePathBuf` values.
11// TODO(anp): Replace the absolute path with a more general instruction-source
12// abstraction when non-filesystem providers need first-class attribution.
13#[derive(Clone, Debug, Eq, PartialEq)]
14pub struct UserInstructions {
15    /// Model-visible user instruction text.
16    pub text: String,
17    /// Absolute filesystem path reported through `instructionSources`.
18    pub source: AbsolutePathBuf,
19}
20
21/// Result of loading host-provided user instructions.
22#[derive(Clone, Debug, Default, Eq, PartialEq)]
23pub struct LoadedUserInstructions {
24    /// Loaded instructions, or `None` when the provider has no applicable text.
25    pub instructions: Option<UserInstructions>,
26    /// Recoverable loading problems that should be surfaced during startup.
27    pub warnings: Vec<String>,
28}
29
30/// Future returned by a [`UserInstructionsProvider`].
31pub type LoadUserInstructionsFuture<'a> =
32    Pin<Box<dyn Future<Output = LoadedUserInstructions> + Send + 'a>>;
33
34/// Loads the user instructions that apply when a root thread runtime starts.
35///
36/// Implementations should return any recoverable loading problems as warnings
37/// while still returning usable fallback instructions when available.
38pub trait UserInstructionsProvider: Send + Sync {
39    /// Loads the snapshot to use for a newly created root runtime.
40    fn load_user_instructions(&self) -> LoadUserInstructionsFuture<'_>;
41}
codex_extension_api/user_instructions.rs

codex_extension_api/
user_instructions.rs
