Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

24.2 KB
Raw Blame
//! AI tools over the import ledger.
//!
//! Chat sessions get the ledger tools plus the single-page Notion import
//! workflow, staging as `initiator = chat`; Notion import jobs get only
//! `FinalizeImport`. The user comes from the request context, so the model
//! can never stage on another user's behalf.

use crate::domain::models::{ImportEntity, ImportSource, ImportStatus, Initiator, metadata_label};
use crate::domain::ports::{ImportError, ImportedDocumentProperties, ImportedDocumentProperty};
use crate::domain::service::{
    DiscardOutcome, ImportFinalizer, ImportNotionPageOutcome, ImportStager, NotionPageImporter,
    StageOutcome, WorkspaceImporter,
};
use ai_toolset::{
    AsyncTool, AsyncToolCollection, RequestContext, ServiceContext, ToolCallError, ToolResult,
};
use ai_toolset::{ToolAnnotated, ToolAnnotations};
use async_trait::async_trait;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use std::sync::Arc;
use uuid::Uuid;

mod import_from_notion;
mod import_from_tracker;
pub use import_from_tracker::{ImportFromJira, ImportFromLinear, TrackerImportResponse};

pub use import_from_notion::{ImportFromNotion, ImportFromNotionResponse, NotionImportAction};

#[cfg(test)]
mod test;

/// Service context for import AI tools.
///
/// The service is optional because the tool schemas ship with the shared
/// chat toolset while only hosts that can build the import service (DB,
/// MCP credentials, gateway) actually wire it. Where it is absent, calls
/// fail with a clear "not available here" error instead of not existing.
pub struct ImportToolContext<T> {
    /// The import service, where the host wired one.
    pub service: Option<Arc<T>>,
}

impl<T> Clone for ImportToolContext<T> {
    fn clone(&self) -> Self {
        Self {
            service: self.service.clone(),
        }
    }
}

impl<T> ImportToolContext<T> {
    /// A context backed by a real import service.
    pub fn wired(service: Arc<T>) -> Self {
        Self {
            service: Some(service),
        }
    }

    /// A context with no import service: every tool call fails with a clear
    /// error. For hosts that share the toolset but cannot build the service.
    pub fn unwired() -> Self {
        Self { service: None }
    }

    fn require_service(&self) -> ToolResult<&Arc<T>> {
        self.service.as_ref().ok_or_else(|| ToolCallError {
            description: "Import tracking is not available in this context.".to_string(),
            internal_error: anyhow::anyhow!("import service not wired into this host"),
        })
    }
}

/// The import toolset for interactive chat.
pub fn import_toolset<T: ImportStager + NotionPageImporter + WorkspaceImporter>()
-> AsyncToolCollection<ImportToolContext<T>> {
    AsyncToolCollection::new()
        .add_tool::<CreateImportEntity, ImportToolContext<T>>()
        .add_tool::<ImportNotionPage, ImportToolContext<T>>()
        .add_tool::<ImportFromNotion, ImportToolContext<T>>()
        .add_tool::<ImportFromLinear, ImportToolContext<T>>()
        .add_tool::<ImportFromJira, ImportToolContext<T>>()
        .add_tool::<DeleteImportEntity, ImportToolContext<T>>()
        .add_tool::<ListImportEntities, ImportToolContext<T>>()
}

/// The finalize-only toolset for Notion import jobs.
pub fn notion_import_toolset<T: ImportFinalizer>() -> AsyncToolCollection<ImportToolContext<T>> {
    AsyncToolCollection::new().add_tool::<FinalizeImport, ImportToolContext<T>>()
}

fn tool_error(description: String, e: impl Into<anyhow::Error>) -> ToolCallError {
    ToolCallError {
        internal_error: e.into(),
        description,
    }
}

fn import_error(context: &str, e: ImportError) -> ToolCallError {
    ToolCallError {
        description: format!("{context}: {e}"),
        internal_error: e.into(),
    }
}

/// Compact row view returned by import tools.
#[derive(Debug, Serialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct ImportEntityView {
    /// Ledger row id (use with DeleteImportEntity).
    pub id: Uuid,
    /// The external system the item comes from.
    pub source: ImportSource,
    /// Stable id in the source system.
    pub foreign_id: String,
    /// Row status.
    pub status: ImportStatus,
    /// A human label from the metadata (title / channel name).
    pub label: String,
    /// The Macro entity it became, when imported.
    pub entity_id: Option<String>,
    /// The Macro entity type, when imported.
    pub entity_type: Option<String>,
    /// Whether the row belongs to a teammate (team-imported), not the user.
    pub imported_by_teammate: bool,
}

impl ImportEntityView {
    fn of(row: &ImportEntity, requesting_user: &str) -> Self {
        Self {
            id: row.id,
            source: row.source,
            foreign_id: row.foreign_id.clone(),
            status: row.status,
            label: metadata_label(row.source, &row.metadata),
            entity_id: row.entity_id.clone(),
            entity_type: row.entity_type.clone(),
            imported_by_teammate: row.user_id != requesting_user,
        }
    }
}

/// Status values accepted by [`CreateImportEntity`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, JsonSchema)]
#[serde(rename_all = "snake_case")]
pub enum CreateImportStatus {
    /// Track an item as a candidate the user has not accepted yet.
    Staged,
    /// Record an item you have ALREADY created a Macro entity for.
    Imported,
}

/// Track an external item in the import ledger.
#[derive(Debug, Clone, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
#[schemars(
    title = "CreateImportEntity",
    description = "Track an external item (Linear issue, Notion page, Slack channel) in the import ledger. Use status `staged` to propose an item for import BEFORE creating anything; use status `imported` (with entityId) only to record a Macro entity you already created from the item. The response tells you when the item was already imported by the user or a teammate — in that case do NOT create a duplicate; point the user at the existing entity instead."
)]
pub struct CreateImportEntity {
    /// The external system the item comes from.
    #[schemars(description = "The external system the item comes from.")]
    pub source: ImportSource,

    /// Stable id of the item in the source system.
    #[schemars(
        description = "Stable id of the item in the source system: the Linear issue identifier (e.g. `ENG-142`), the Notion page URL or id, or the Slack channel id (e.g. `C0123456789`, falling back to the channel name)."
    )]
    pub foreign_id: String,

    /// Whether this is a staged candidate or an already-created import.
    #[schemars(
        description = "`staged` to propose the item for import; `imported` to record a Macro entity you already created from it (requires entityId)."
    )]
    pub status: CreateImportStatus,

    /// Per-source metadata describing the item.
    #[schemars(
        description = "Metadata describing the item. Linear: {identifier, title, description?, status?, priority?, assignee?, assignee_email?, url?}. Notion: {title, url?, summary?} — never include page content. Slack: {name, channel_id?, purpose?, participants?: [{name, email?}]}."
    )]
    pub metadata: serde_json::Value,

    /// The Macro entity id, when `status` is `imported`.
    #[schemars(
        description = "The id of the Macro entity you created, required when status is `imported`. The entity type is fixed by source: linear → task, notion → md (document), slack → channel."
    )]
    #[serde(default)]
    pub entity_id: Option<String>,
}

/// Response from tracking an item.
#[derive(Debug, Serialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct CreateImportEntityResponse {
    /// What happened: `staged`, `recorded_imported`, `already_imported`,
    /// `already_imported_by_teammate`, `previously_declined`, or
    /// `import_in_progress`.
    pub outcome: String,
    /// The ledger row backing the outcome.
    pub entity: ImportEntityView,
    /// What to do with this outcome.
    pub message: String,
}

impl ToolAnnotated for CreateImportEntity {
    const ANNOTATIONS: ToolAnnotations = ToolAnnotations::additive("Track import candidate");
}

#[async_trait]
impl<T: ImportStager> AsyncTool<ImportToolContext<T>> for CreateImportEntity {
    type Output = CreateImportEntityResponse;

    #[tracing::instrument(skip_all, fields(user_id = %request_context.user_id, source = self.source.as_ref(), foreign_id = %self.foreign_id), err)]
    async fn call(
        &self,
        service_context: ServiceContext<ImportToolContext<T>>,
        request_context: RequestContext,
    ) -> ToolResult<Self::Output> {
        let user = request_context.user_id.clone();

        match self.status {
            CreateImportStatus::Staged => {
                let outcome = service_context
                    .require_service()?
                    .stage(
                        &user,
                        Initiator::Chat,
                        self.source,
                        &self.foreign_id,
                        self.metadata.clone(),
                    )
                    .await
                    .map_err(|e| import_error("Failed to stage item", e))?;
                Ok(stage_response(outcome, user.as_ref()))
            }
            CreateImportStatus::Imported => {
                let Some(entity_id) = self
                    .entity_id
                    .as_deref()
                    .map(str::trim)
                    .filter(|s| !s.is_empty())
                else {
                    return Err(tool_error(
                        "entityId is required when status is `imported` — pass the id of the \
                         Macro entity you created."
                            .to_string(),
                        anyhow::anyhow!("missing entity_id"),
                    ));
                };
                let row = service_context
                    .require_service()?
                    .record_imported(
                        &user,
                        Initiator::Chat,
                        self.source,
                        &self.foreign_id,
                        self.metadata.clone(),
                        entity_id,
                    )
                    .await
                    .map_err(|e| import_error("Failed to record import", e))?;
                Ok(CreateImportEntityResponse {
                    outcome: "recorded_imported".into(),
                    message: format!(
                        "Recorded {} as imported.",
                        metadata_label(row.source, &row.metadata)
                    ),
                    entity: ImportEntityView::of(&row, user.as_ref()),
                })
            }
        }
    }
}

fn stage_response(outcome: StageOutcome, user: &str) -> CreateImportEntityResponse {
    match outcome {
        StageOutcome::Staged(row) => CreateImportEntityResponse {
            outcome: "staged".into(),
            message: format!(
                "Staged {} for import. It will be imported when the user accepts it.",
                metadata_label(row.source, &row.metadata)
            ),
            entity: ImportEntityView::of(&row, user),
        },
        StageOutcome::AlreadyImported {
            entity,
            by_teammate,
        } => CreateImportEntityResponse {
            outcome: if by_teammate {
                "already_imported_by_teammate".into()
            } else {
                "already_imported".into()
            },
            message: format!(
                "{} was already imported{} as {} `{}`. Do NOT create a duplicate — tell the \
                 user it already exists and reference the existing entity.",
                metadata_label(entity.source, &entity.metadata),
                if by_teammate {
                    " by a teammate into the team"
                } else {
                    ""
                },
                entity.entity_type.as_deref().unwrap_or("entity"),
                entity.entity_id.as_deref().unwrap_or("?"),
            ),
            entity: ImportEntityView::of(&entity, user),
        },
        StageOutcome::PreviouslyDiscarded(row) => CreateImportEntityResponse {
            outcome: "previously_declined".into(),
            message: format!(
                "The user previously declined {}; it was not re-staged. Skip it.",
                metadata_label(row.source, &row.metadata)
            ),
            entity: ImportEntityView::of(&row, user),
        },
        StageOutcome::ImportInProgress(row) => CreateImportEntityResponse {
            outcome: "import_in_progress".into(),
            message: "An import is already running for this item; leave it alone.".into(),
            entity: ImportEntityView::of(&row, user),
        },
    }
}

/// Import one specific Notion page as a Macro markdown document.
#[derive(Debug, Clone, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
#[schemars(
    title = "ImportNotionPage",
    description = "Import one specific Notion page through Macro's canonical Notion importer. Use this when the user explicitly asks to import a page URL or id. The tool performs deduplication, fetches through the user's connected Notion MCP, normalizes the page, creates the Macro markdown document, and returns its entity id. Do not fetch and recreate the page manually with generic document tools. Notion databases and database-first pages are intentionally not imported."
)]
pub struct ImportNotionPage {
    /// The exact Notion page URL or stable 32-character page id.
    #[schemars(
        description = "The exact Notion page URL or stable 32-character Notion page id to import."
    )]
    pub page_url: String,
}

/// Response from importing one Notion page.
#[derive(Debug, Serialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct ImportNotionPageResponse {
    /// What happened: `imported`, `already_imported`,
    /// `already_imported_by_teammate`, `previously_declined`, or
    /// `import_in_progress`.
    pub outcome: String,
    /// The ledger row and Macro entity id, when one exists.
    pub entity: ImportEntityView,
    /// Human-readable result and next action.
    pub message: String,
}

impl ToolAnnotated for ImportNotionPage {
    const ANNOTATIONS: ToolAnnotations =
        ToolAnnotations::additive("Import Notion page").with_open_world();
}

#[async_trait]
impl<T: NotionPageImporter> AsyncTool<ImportToolContext<T>> for ImportNotionPage {
    type Output = ImportNotionPageResponse;

    #[tracing::instrument(skip_all, fields(user_id = %request_context.user_id, page_url = %self.page_url), err)]
    async fn call(
        &self,
        service_context: ServiceContext<ImportToolContext<T>>,
        request_context: RequestContext,
    ) -> ToolResult<Self::Output> {
        let page_url = self.page_url.trim();
        if page_url.is_empty() {
            return Err(tool_error(
                "A Notion page URL or id is required.".to_string(),
                anyhow::anyhow!("empty Notion page URL"),
            ));
        }

        let user = request_context.user_id.clone();
        let outcome = service_context
            .require_service()?
            .import_notion_page(&user, page_url)
            .await
            .map_err(|e| import_error("Failed to import Notion page", e))?;

        Ok(match outcome {
            ImportNotionPageOutcome::Imported {
                entity,
                already_existed,
                by_teammate,
            } => {
                let outcome = if by_teammate {
                    "already_imported_by_teammate"
                } else if already_existed {
                    "already_imported"
                } else {
                    "imported"
                };
                let message = if already_existed {
                    format!(
                        "This Notion page was already imported{} as Macro document `{}`. Do not create a duplicate.",
                        if by_teammate { " by a teammate" } else { "" },
                        entity.entity_id.as_deref().unwrap_or("?"),
                    )
                } else {
                    format!(
                        "Imported the Notion page as Macro document `{}`.",
                        entity.entity_id.as_deref().unwrap_or("?"),
                    )
                };
                ImportNotionPageResponse {
                    outcome: outcome.to_string(),
                    entity: ImportEntityView::of(&entity, user.as_ref()),
                    message,
                }
            }
            ImportNotionPageOutcome::PreviouslyDiscarded(entity) => ImportNotionPageResponse {
                outcome: "previously_declined".to_string(),
                message: "The user previously declined this page, so it was not imported."
                    .to_string(),
                entity: ImportEntityView::of(&entity, user.as_ref()),
            },
            ImportNotionPageOutcome::ImportInProgress(entity) => ImportNotionPageResponse {
                outcome: "import_in_progress".to_string(),
                message: "This Notion page is already being imported. Do not start a duplicate."
                    .to_string(),
                entity: ImportEntityView::of(&entity, user.as_ref()),
            },
        })
    }
}

/// Decline a staged import candidate.
#[derive(Debug, Clone, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
#[schemars(
    title = "DeleteImportEntity",
    description = "Decline a staged import candidate on the user's behalf. The item is remembered as declined so it won't be proposed again; only the user's own staged items can be declined."
)]
pub struct DeleteImportEntity {
    /// The ledger row id to decline.
    #[schemars(
        description = "The import entity id to decline (from CreateImportEntity or ListImportEntities)."
    )]
    pub id: Uuid,
}

/// Response from declining a candidate.
#[derive(Debug, Serialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct DeleteImportEntityResponse {
    /// Whether the row is now discarded.
    pub discarded: bool,
    /// What happened.
    pub message: String,
}

impl ToolAnnotated for DeleteImportEntity {
    const ANNOTATIONS: ToolAnnotations = ToolAnnotations::destructive("Decline import candidate");
}

#[async_trait]
impl<T: ImportStager> AsyncTool<ImportToolContext<T>> for DeleteImportEntity {
    type Output = DeleteImportEntityResponse;

    #[tracing::instrument(skip_all, fields(user_id = %request_context.user_id, id = %self.id), err)]
    async fn call(
        &self,
        service_context: ServiceContext<ImportToolContext<T>>,
        request_context: RequestContext,
    ) -> ToolResult<Self::Output> {
        let outcome = service_context
            .require_service()?
            .discard_entity(&request_context.user_id.clone(), self.id)
            .await
            .map_err(|e| import_error("Failed to decline item", e))?;
        match outcome {
            DiscardOutcome::Discarded => Ok(DeleteImportEntityResponse {
                discarded: true,
                message: "Declined. It won't be proposed again.".into(),
            }),
            DiscardOutcome::NotFound => Err(tool_error(
                format!("No import entity `{}` belongs to this user.", self.id),
                anyhow::anyhow!("not found"),
            )),
            DiscardOutcome::NotDiscardable(status) => Err(tool_error(
                format!(
                    "Import entity `{}` is `{}`; only staged items can be declined.",
                    self.id,
                    status.as_ref()
                ),
                anyhow::anyhow!("not discardable"),
            )),
        }
    }
}

/// List import ledger rows.
#[derive(Debug, Clone, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
#[schemars(
    title = "ListImportEntities",
    description = "List the user's import ledger: staged candidates, in-flight imports, imported items (including ones teammates imported into the team), and declined items. Use this to check what already exists before proposing or creating imports."
)]
pub struct ListImportEntities {
    /// Filter to one source.
    #[schemars(description = "Filter to one source system.")]
    #[serde(default)]
    pub source: Option<ImportSource>,

    /// Filter to one status.
    #[schemars(
        description = "Filter to one status: staged, importing, imported, or discarded. Omit for all."
    )]
    #[serde(default)]
    pub status: Option<ImportStatus>,
}

/// Response from listing the ledger.
#[derive(Debug, Serialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct ListImportEntitiesResponse {
    /// The visible rows, newest first.
    pub entities: Vec<ImportEntityView>,
}

impl ToolAnnotated for ListImportEntities {
    const ANNOTATIONS: ToolAnnotations = ToolAnnotations::read_only("List import ledger");
}

#[async_trait]
impl<T: ImportStager> AsyncTool<ImportToolContext<T>> for ListImportEntities {
    type Output = ListImportEntitiesResponse;

    #[tracing::instrument(skip_all, fields(user_id = %request_context.user_id), err)]
    async fn call(
        &self,
        service_context: ServiceContext<ImportToolContext<T>>,
        request_context: RequestContext,
    ) -> ToolResult<Self::Output> {
        let user = request_context.user_id.clone();
        let rows = service_context
            .require_service()?
            .list_entities(&user, self.source, self.status)
            .await
            .map_err(|e| import_error("Failed to list import entities", e))?;
        Ok(ListImportEntitiesResponse {
            entities: rows
                .iter()
                .map(|row| ImportEntityView::of(row, user.as_ref()))
                .collect(),
        })
    }
}

/// Finalize one importing row as a Macro document.
#[derive(Debug, Clone, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
#[schemars(
    title = "FinalizeImport",
    description = "Create the Macro document for one accepted import item and mark it imported. Call exactly once per item you were asked to import."
)]
pub struct FinalizeImport {
    /// The importing ledger row to finalize.
    #[schemars(description = "The import_id of the item, as listed in the instructions.")]
    pub import_id: Uuid,

    /// The document name.
    #[schemars(description = "The name for the created document (usually the item's title).")]
    pub name: String,

    /// The document body.
    #[schemars(description = "The full markdown body for the created document.")]
    pub content_markdown: String,

    /// Notion database properties to attach to the document.
    #[serde(default)]
    #[schemars(
        description = "Useful non-title Notion page properties, typed for Macro. Omit unsupported or empty values."
    )]
    pub properties: Vec<ImportedDocumentProperty>,

    /// Notion labels/tags to attach as Macro tags.
    #[serde(default)]
    #[schemars(description = "Labels from Notion properties named Tags, Tag, Labels, or Label.")]
    pub tags: Vec<String>,
}

/// Response from finalizing an item.
#[derive(Debug, Serialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct FinalizeImportResponse {
    /// The Macro entity id that now exists.
    pub entity_id: String,
    /// The Macro entity type.
    pub entity_type: String,
}

impl ToolAnnotated for FinalizeImport {
    const ANNOTATIONS: ToolAnnotations = ToolAnnotations::additive("Finalize import");
}

#[async_trait]
impl<T: ImportFinalizer> AsyncTool<ImportToolContext<T>> for FinalizeImport {
    type Output = FinalizeImportResponse;

    #[tracing::instrument(skip_all, fields(user_id = %request_context.user_id, import_id = %self.import_id), err)]
    async fn call(
        &self,
        service_context: ServiceContext<ImportToolContext<T>>,
        request_context: RequestContext,
    ) -> ToolResult<Self::Output> {
        let row = service_context
            .require_service()?
            .finalize_document(
                &request_context.user_id.clone(),
                self.import_id,
                self.name.trim(),
                &self.content_markdown,
                &ImportedDocumentProperties {
                    values: self.properties.clone(),
                    tags: self.tags.clone(),
                },
            )
            .await
            .map_err(|e| import_error("Failed to finalize import", e))?;
        Ok(FinalizeImportResponse {
            entity_id: row.entity_id.unwrap_or_default(),
            entity_type: row.entity_type.unwrap_or_default(),
        })
    }
}