Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
#![deny(missing_docs)]
//! Bot identity primitives.
use cowlike::{ArcCowStr, CowLike};
use nom::{
Finish, IResult, Parser,
bytes::complete::tag,
character::complete::char,
combinator::{eof, map_res, recognize},
};
use serde::{Deserialize, Serialize};
use uuid::Uuid;
pub use cowlike;
#[cfg(test)]
mod test;
const BOT_STORAGE_PREFIX: &str = "bot";
const UUID_HYPHENATED_LEN: usize = 36;
fn uuid_literal(input: &str) -> IResult<&str, BotId> {
map_res(
recognize(nom::bytes::complete::take_while_m_n(
UUID_HYPHENATED_LEN,
UUID_HYPHENATED_LEN,
|c: char| c.is_ascii_hexdigit() || c == '-',
)),
|value| Uuid::parse_str(value).map(BotId),
)
.parse(input)
}
fn bot_id_str(input: &str) -> IResult<&str, BotIdStorage<ArcCowStr<'_>>> {
let (rest, (((prefix, pipe), bot_id), _eof)) = tag(BOT_STORAGE_PREFIX)
.and(char('|'))
.and(uuid_literal)
.and(eof)
.parse(input)?;
let bot_id_part_offset = prefix.len() + pipe.len_utf8();
Ok((
rest,
BotIdStorage {
bot_id,
bot_id_part_offset,
storage_id: ArcCowStr::Borrowed(input),
},
))
}
/// Stable [`BotId`] for the classic first-party "Macro" system bot.
///
/// Mentioning it answers with the classic in-channel chat reply (the
/// `channel_bots` agent loop in `document_storage_service`). Agent sessions
/// belong to [`MACRO_NEW_BOT_ID`] instead.
pub const MACRO_AI_BOT_ID: BotId =
BotId::new_from_uuid(Uuid::from_u128(0x0000_0000_0000_0000_0000_0000_0000_a1a1));
/// Stable handle for the classic "Macro" system bot (used for `@` mentions).
pub const MACRO_AI_HANDLE: &str = "macro";
/// Display name for Macro, shared by both of its bot ids.
pub const MACRO_AI_NAME: &str = "Macro";
/// Stable [`BotId`] for the agent-session half of Macro.
///
/// Mentioning it opens an agent session served by the in-process (in-memory)
/// agent harness, which answers with the Macro product toolset. A separate bot
/// from [`MACRO_AI_BOT_ID`] because one id cannot mean both a chat reply and a
/// session - but the same persona to a reader: both are named "Macro", and the
/// web client's chat-v3 rollout decides which of the two a single `@macro`
/// mention targets.
pub const MACRO_NEW_BOT_ID: BotId =
BotId::new_from_uuid(Uuid::from_u128(0x0000_0000_0000_0000_0000_0000_0000_a2a2));
/// Stable handle for the agent-session Macro bot.
///
/// Distinct from [`MACRO_AI_HANDLE`] only because handles identify a bot;
/// nothing offers it as a second `@` entry. The display name is
/// [`MACRO_AI_NAME`], the same as the classic bot's.
pub const MACRO_NEW_HANDLE: &str = "macro-new";
/// Stable [`BotId`] for autonomous Macro platform operations.
pub const MACRO_SYSTEM_BOT_ID: BotId =
BotId::new_from_uuid(Uuid::from_u128(0x0000_0000_0000_0000_0000_0000_0000_5759));
/// Display name for the autonomous Macro platform principal.
pub const MACRO_SYSTEM_NAME: &str = "Macro System";
/// Stable [`BotId`] for the "Macro Coder" system bot, our coding-agent harness.
///
/// Distinct from [`MACRO_AI_BOT_ID`] on purpose: the Macro bot's sessions run
/// in-process on the in-memory harness, while this one's run in a provisioned
/// sandbox, and one id cannot mean both.
pub const MACRO_CODER_BOT_ID: BotId =
BotId::new_from_uuid(Uuid::from_u128(0x0000_0000_0000_0000_0000_0000_0000_a9e7));
/// Stable handle for the "Macro Coder" system bot (used for `@` mentions).
pub const MACRO_CODER_HANDLE: &str = "coder";
/// Display name for the "Macro Coder" system bot.
pub const MACRO_CODER_NAME: &str = "Macro Coder";
/// Stable [`BotId`] for the "Cursor" system bot.
///
/// Mentioning it opens an agent session like [`MACRO_CODER_BOT_ID`] does, but
/// the session is served by a Cursor cloud agent rather than a Macro-managed
/// sandbox.
pub const CURSOR_BOT_ID: BotId =
BotId::new_from_uuid(Uuid::from_u128(0x0000_0000_0000_0000_0000_0000_0000_c5c5));
/// Stable handle for the "Cursor" system bot (used for `@` mentions).
pub const CURSOR_HANDLE: &str = "cursor";
/// Display name for the "Cursor" system bot.
pub const CURSOR_NAME: &str = "Cursor";
/// Stable identity for the per-owner Codex cloud agent.
pub const CODEX_BOT_ID: BotId = BotId::new_from_uuid(Uuid::from_u128(0xc0de));
/// Mention handle for Codex.
pub const CODEX_HANDLE: &str = "codex";
/// Display name for Codex.
pub const CODEX_NAME: &str = "Codex";
/// Stable handle for the autonomous Macro platform principal.
pub const MACRO_SYSTEM_HANDLE: &str = "macro-system";
/// A first-party bot.
///
/// System bots live here rather than in the `bots` table. Their ids are
/// compile-time constants, so a row would only be a second copy of this one
/// that an environment could be missing - which is exactly how a deployment
/// ends up serving a bot it cannot look up. Only user- and team-owned bots
/// are rows.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SystemBot {
/// Stable id.
pub id: BotId,
/// Display name.
pub name: &'static str,
/// Handle used for `@` mentions.
pub handle: &'static str,
/// Whether mentioning this bot opens an agent session.
pub has_agent: bool,
}
/// Every first-party bot.
pub const SYSTEM_BOTS: &[SystemBot] = &[
// Answers in channel via the classic `channel_bots` reply loop, which
// needs no agent session; its next-generation replacement below is the
// one whose mentions open sessions.
SystemBot {
id: MACRO_AI_BOT_ID,
name: MACRO_AI_NAME,
handle: MACRO_AI_HANDLE,
has_agent: false,
},
// The same persona as the bot above, under a second id because only this
// one opens sessions. It carries the same name for the same reason.
SystemBot {
id: MACRO_NEW_BOT_ID,
name: MACRO_AI_NAME,
handle: MACRO_NEW_HANDLE,
has_agent: true,
},
SystemBot {
id: MACRO_CODER_BOT_ID,
name: MACRO_CODER_NAME,
handle: MACRO_CODER_HANDLE,
has_agent: true,
},
SystemBot {
id: CURSOR_BOT_ID,
name: CURSOR_NAME,
handle: CURSOR_HANDLE,
has_agent: true,
},
SystemBot {
id: CODEX_BOT_ID,
name: CODEX_NAME,
handle: CODEX_HANDLE,
has_agent: true,
},
// Posts as itself for autonomous platform operations, but nothing mentions
// it and it opens no sessions.
SystemBot {
id: MACRO_SYSTEM_BOT_ID,
name: MACRO_SYSTEM_NAME,
handle: MACRO_SYSTEM_HANDLE,
has_agent: false,
},
];
/// The first-party bot with this id, when it is one.
#[must_use]
pub fn system_bot(id: BotId) -> Option<&'static SystemBot> {
SYSTEM_BOTS.iter().find(|bot| bot.id == id)
}
/// The first-party bot with this handle, when it is one.
#[must_use]
pub fn system_bot_by_handle(handle: &str) -> Option<&'static SystemBot> {
SYSTEM_BOTS.iter().find(|bot| bot.handle == handle)
}
/// The handle users type to reach the bot `id`, whose own handle is `handle`.
///
/// Macro's agent-session bot is reached through `@macro`; its own handle,
/// [`MACRO_NEW_HANDLE`], only tells it apart from the classic bot.
#[must_use]
pub fn mention_handle(id: BotId, handle: &str) -> &str {
if id == MACRO_NEW_BOT_ID {
MACRO_AI_HANDLE
} else {
handle
}
}
/// Whether `id` is a first-party bot, and so has no `bots` row.
#[must_use]
pub fn is_system_bot(id: BotId) -> bool {
system_bot(id).is_some()
}
/// A bot id that is not in [`SYSTEM_BOTS`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct NonSystemBotId(BotId);
impl NonSystemBotId {
/// Accept `id` only when it is not a first-party bot.
#[must_use]
pub fn new(id: BotId) -> Option<Self> {
(!is_system_bot(id)).then_some(Self(id))
}
/// Return the underlying bot id.
pub const fn get(self) -> BotId {
self.0
}
}
/// A bot id UUID.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(transparent)]
pub struct BotId(Uuid);
impl BotId {
#[cfg(any(test, feature = "test-utils"))]
#[allow(missing_docs)]
pub const TEST_A: Self = Self(Uuid::from_u128(0xB07A));
#[cfg(any(test, feature = "test-utils"))]
#[allow(missing_docs)]
pub const TEST_B: Self = Self(Uuid::from_u128(0xB07B));
/// Build a bot id from its UUID.
pub const fn new_from_uuid(id: Uuid) -> Self {
Self(id)
}
/// Return the underlying UUID.
pub const fn as_uuid(self) -> Uuid {
self.0
}
/// Parse a bot id from its UUID string representation.
pub fn parse_uuid_str(value: &str) -> Result<Self, BotIdParseError> {
Uuid::parse_str(value)
.map(Self)
.map_err(|_| BotIdParseError::invalid(value))
}
/// Canonical storage representation as a parsed [`BotIdStr`].
pub fn into_storage_id(self) -> BotIdStr<'static> {
let storage_id = format!("{BOT_STORAGE_PREFIX}|{}", self.0);
BotIdStr(BotIdStorage {
bot_id: self,
bot_id_part_offset: BOT_STORAGE_PREFIX.len() + 1,
storage_id: ArcCowStr::Owned(storage_id.into()),
})
}
}
impl std::fmt::Display for BotId {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "{}", self.0)
}
}
impl std::str::FromStr for BotId {
type Err = BotIdParseError;
fn from_str(value: &str) -> Result<Self, Self::Err> {
Self::parse_uuid_str(value)
}
}
/// A parsed bot storage principal, `bot|<uuid>`.
#[derive(Clone, Copy)]
pub struct BotIdStorage<T> {
bot_id: BotId,
bot_id_part_offset: usize,
storage_id: T,
}
impl<T> std::fmt::Debug for BotIdStorage<T>
where
T: AsRef<str>,
{
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "{}", self.storage_id.as_ref())
}
}
impl<T> PartialEq for BotIdStorage<T>
where
T: PartialEq,
{
fn eq(&self, other: &Self) -> bool {
self.bot_id == other.bot_id
}
}
impl<T> Eq for BotIdStorage<T> where T: Eq {}
impl<T> std::hash::Hash for BotIdStorage<T>
where
T: std::hash::Hash,
{
fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
self.bot_id.hash(state);
}
}
impl<T> BotIdStorage<T> {
fn map<F, U>(self, f: F) -> BotIdStorage<U>
where
F: FnOnce(T) -> U,
{
BotIdStorage {
bot_id: self.bot_id,
bot_id_part_offset: self.bot_id_part_offset,
storage_id: f(self.storage_id),
}
}
}
impl<T> AsRef<str> for BotIdStorage<T>
where
T: AsRef<str>,
{
fn as_ref(&self) -> &str {
self.storage_id.as_ref()
}
}
impl<T> BotIdStorage<T>
where
T: AsRef<str>,
{
/// Return the parsed bot UUID newtype.
pub const fn bot_id(&self) -> BotId {
self.bot_id
}
/// Return the UUID portion as a string slice.
pub fn uuid_str(&self) -> &str {
let storage_id = self.storage_id.as_ref();
&storage_id[self.bot_id_part_offset..]
}
}
impl<'a, T> CowLike<'a> for BotIdStorage<T>
where
T: CowLike<'a>,
{
type Owned<'b> = BotIdStorage<T::Owned<'b>>;
fn into_owned(self) -> BotIdStorage<T::Owned<'static>> {
self.map(CowLike::into_owned)
}
fn copied(&'a self) -> Self {
BotIdStorage {
bot_id: self.bot_id,
bot_id_part_offset: self.bot_id_part_offset,
storage_id: self.storage_id.copied(),
}
}
}
impl<'a> BotIdStorage<ArcCowStr<'a>> {
/// Attempt to create a borrowed parsed bot storage principal from an input string.
pub fn parse_from_str(input: &'a str) -> Result<Self, BotIdParseError> {
let (_, out) = bot_id_str(input)
.finish()
.map_err(|_| BotIdParseError::invalid(input))?;
Ok(out)
}
}
/// The standard string newtype for a parsed bot storage principal, `bot|<uuid>`.
#[derive(Clone, Serialize, Deserialize, PartialEq, Eq, Hash)]
#[serde(try_from = "String", into = "String")]
pub struct BotIdStr<'a>(pub BotIdStorage<ArcCowStr<'a>>);
impl<'a> std::fmt::Debug for BotIdStr<'a> {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "{}", self.0.as_ref())
}
}
impl<'a> std::fmt::Display for BotIdStr<'a> {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(f, "{}", self.0.as_ref())
}
}
impl<'a> AsRef<str> for BotIdStr<'a> {
fn as_ref(&self) -> &str {
self.0.as_ref()
}
}
impl<'a> BotIdStr<'a> {
/// Parse the inner value from the input string.
pub fn parse_from_str(s: &'a str) -> Result<Self, BotIdParseError> {
BotIdStorage::parse_from_str(s).map(BotIdStr)
}
/// Return the parsed bot UUID newtype.
pub const fn bot_id(&self) -> BotId {
self.0.bot_id
}
/// Return the parsed UUID.
pub const fn as_uuid(&self) -> Uuid {
self.0.bot_id.as_uuid()
}
}
impl From<BotId> for BotIdStr<'static> {
fn from(value: BotId) -> Self {
BotId::into_storage_id(value)
}
}
impl TryFrom<String> for BotIdStr<'static> {
type Error = BotIdParseError;
fn try_from(value: String) -> Result<Self, Self::Error> {
let s = value.as_str();
BotIdStr::try_from(s).map(|x| x.into_owned())
}
}
impl<'a> TryFrom<&'a str> for BotIdStr<'a> {
type Error = BotIdParseError;
fn try_from(value: &'a str) -> Result<Self, Self::Error> {
Self::parse_from_str(value)
}
}
impl From<BotIdStr<'_>> for String {
fn from(value: BotIdStr<'_>) -> Self {
value.0.as_ref().to_string()
}
}
impl<'a> CowLike<'a> for BotIdStr<'a> {
type Owned<'b> = BotIdStr<'b>;
fn into_owned(self) -> Self::Owned<'static> {
BotIdStr(self.0.into_owned())
}
fn copied(&'a self) -> Self {
BotIdStr(self.0.copied())
}
}
/// Error returned when a bot id cannot be parsed.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
#[error("invalid bot id: {value}")]
pub struct BotIdParseError {
value: String,
}
impl BotIdParseError {
fn invalid(value: &str) -> Self {
Self {
value: value.to_string(),
}
}
}
#[cfg(feature = "schema")]
impl utoipa::ToSchema for BotId {
fn name() -> std::borrow::Cow<'static, str> {
std::borrow::Cow::Borrowed("BotId")
}
}
#[cfg(feature = "schema")]
impl utoipa::PartialSchema for BotId {
fn schema() -> utoipa::openapi::RefOr<utoipa::openapi::schema::Schema> {
String::schema()
}
}
#[cfg(feature = "sqlx")]
impl sqlx::Type<sqlx::Postgres> for BotId {
fn type_info() -> sqlx::postgres::PgTypeInfo {
<Uuid as sqlx::Type<sqlx::Postgres>>::type_info()
}
fn compatible(ty: &sqlx::postgres::PgTypeInfo) -> bool {
<Uuid as sqlx::Type<sqlx::Postgres>>::compatible(ty)
}
}
#[cfg(feature = "sqlx")]
impl sqlx::postgres::PgHasArrayType for BotId {
fn array_type_info() -> sqlx::postgres::PgTypeInfo {
<Uuid as sqlx::postgres::PgHasArrayType>::array_type_info()
}
}
#[cfg(feature = "sqlx")]
impl<'q> sqlx::Encode<'q, sqlx::Postgres> for BotId {
fn encode_by_ref(
&self,
buf: &mut sqlx::postgres::PgArgumentBuffer,
) -> Result<sqlx::encode::IsNull, sqlx::error::BoxDynError> {
<Uuid as sqlx::Encode<sqlx::Postgres>>::encode_by_ref(&self.0, buf)
}
fn size_hint(&self) -> usize {
<Uuid as sqlx::Encode<sqlx::Postgres>>::size_hint(&self.0)
}
}
#[cfg(feature = "sqlx")]
impl<'r> sqlx::Decode<'r, sqlx::Postgres> for BotId {
fn decode(value: sqlx::postgres::PgValueRef<'r>) -> Result<Self, sqlx::error::BoxDynError> {
let value = <Uuid as sqlx::Decode<sqlx::Postgres>>::decode(value)?;
Ok(Self(value))
}
}
#[cfg(feature = "sqlx")]
impl<'r> sqlx::Decode<'r, sqlx::Postgres> for BotIdStr<'static> {
fn decode(value: sqlx::postgres::PgValueRef<'r>) -> Result<Self, sqlx::error::BoxDynError> {
let value = <String as sqlx::Decode<sqlx::Postgres>>::decode(value)?;
BotIdStr::try_from(value).map_err(Into::into)
}
}