Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

20.2 KB
Raw Blame
//! Agent tools giving a running flow a private, tag-scoped slice of memory,
//! plus the flow-memory helpers every flow memory caller shares.
//!
//! Memory v2 has no namespaces: a flow's items are the items carrying its
//! [`flow_tag`] (`flow:<flow_id>`). Every flow write also carries
//! [`FLOWS_TAG`] (`flows`), which is what the read-only cross-flow
//! `scope: "flows"` recall filters on. A keyed write additionally carries
//! [`flow_key_tag`] (`flow:<flow_id>:key:<key>`) so it can be replaced and
//! forgotten by key.
//!
//! Motivating use case: a newsletter-digest flow that runs on a schedule
//! needs to remember which items it already sent so it doesn't re-send them
//! on the next run.
//!
//! **Security invariant (non-negotiable):** there is no code path here by
//! which a flow can write an item tagged for another flow. Every write
//! derives its tags from the run's trusted `TrustedAutomation { Workflow }`
//! origin ([`trusted_flow_id`]), never from a model-supplied `flow_id`
//! argument; outside a trusted workflow run the write is refused outright.
//! Flow writes are stored as `source.kind = agent` learnings with the flow
//! tags, so they never pose as user-authored conversation or documents.
//! [`FlowMemoryRecallTool`] only ever reads with a flow tag filter
//! (`flow:<id>` or `flows`), so it never reaches the user's own memory.

use std::sync::Arc;
use tinyagents_harness_tools::static_schema;

use async_trait::async_trait;
use serde_json::json;
use tinymemory_api::{Citation, LearningKind, MemoryMeta, MetaFilter, SourceKind, SourceRef};
use tinytools::{PermissionLevel, Tool, ToolResult};

use crate::config::Config;
use crate::memory::types::{ForgetParams, ItemsListParams, LearnParams, RecallParams, MAX_LIMIT};
use crate::security::policy::ToolOperation;
use crate::security::turn_origin::{AgentTurnOrigin, TrustedAutomationSource};
use crate::security::SecurityPolicy;
use tinymemory_api::{Error, Result};

/// Prefix of a flow's own tag (see [`flow_tag`]).
pub const FLOW_TAG_PREFIX: &str = "flow:";

/// Tag carried by every flow-written item; the cross-flow (`scope: "flows"`)
/// read filter.
pub const FLOWS_TAG: &str = "flows";

/// Infix between a flow's tag and a key in [`flow_key_tag`].
const FLOW_KEY_INFIX: &str = ":key:";

/// Returns the flow id the *run itself* is scoped under, when the current
/// agent turn is executing inside a saved-flow run
/// (`AgentTurnOrigin::TrustedAutomation { job_id, source: Workflow { .. } }` —
/// see `flows::ops::workflow_origin`). `job_id` on that variant IS the
/// running flow's id.
///
/// **Security invariant:** this is the ONLY trustworthy source of "which flow
/// is calling". A `flow_id` tool argument is model-supplied and can be forged
/// by a prompt-injected caller. Writes refuse when this is `None`; the
/// read-only recall falls back to the argument (cross-flow reads are already
/// open by design, so an argument grants no new read privilege).
fn trusted_flow_id(origin: Option<&AgentTurnOrigin>) -> Option<String> {
    match origin {
        Some(AgentTurnOrigin::TrustedAutomation {
            job_id,
            source: TrustedAutomationSource::Workflow { .. },
        }) => Some(job_id.clone()),
        _ => None,
    }
}

/// The tag marking an item as `flow_id`'s own.
///
/// **Security invariant:** the only constructor of flow tags. Every caller —
/// the agent tools below, the tinyflows `memory` node adapter, the post-run
/// digest subscriber and `flows_delete` — passes a trusted flow id.
#[must_use]
pub fn flow_tag(flow_id: &str) -> String {
    format!("{FLOW_TAG_PREFIX}{flow_id}")
}

/// The tag marking an item as `flow_id`'s value for `key`.
#[must_use]
pub fn flow_key_tag(flow_id: &str, key: &str) -> String {
    format!("{FLOW_TAG_PREFIX}{flow_id}{FLOW_KEY_INFIX}{key}")
}

/// The key a flow item was written under, recovered from its tags.
#[must_use]
pub fn flow_key_of(meta: &MemoryMeta) -> Option<&str> {
    meta.tags.iter().find_map(|tag| {
        tag.strip_prefix(FLOW_TAG_PREFIX)
            .and_then(|rest| rest.split_once(FLOW_KEY_INFIX))
            .map(|(_, key)| key)
    })
}

/// The filter matching every item `flow_id` wrote.
#[must_use]
pub fn flow_filter(flow_id: &str) -> MetaFilter {
    MetaFilter::tags_any([flow_tag(flow_id)])
}

/// The filter matching every flow-written item, of any flow.
#[must_use]
pub fn cross_flow_filter() -> MetaFilter {
    MetaFilter::tags_any([FLOWS_TAG])
}

/// Host metadata for an item `flow_id` writes: `source.kind = agent` with the
/// flow tag as its source id, tagged [`flow_tag`], [`FLOWS_TAG`] and `extra`.
#[must_use]
pub fn flow_meta(flow_id: &str, extra: &[String]) -> MemoryMeta {
    let tag = flow_tag(flow_id);
    let mut tags = vec![tag.clone(), FLOWS_TAG.to_string()];
    tags.extend(extra.iter().cloned());
    MemoryMeta {
        source: SourceRef {
            kind: SourceKind::Agent,
            id: Some(tag),
        },
        tags,
        ..MemoryMeta::default()
    }
}

/// Forgets every item matching `filter` (which must be non-empty). Memory
/// off forgets nothing.
pub async fn forget_matching(config: &Config, filter: MetaFilter) -> Result<usize> {
    if filter.is_empty() {
        return Err(Error::InvalidRequest(
            ("refusing to forget with an empty filter").into(),
        ));
    }
    match crate::memory::ops::forget_filter(config, filter).await {
        Ok(forgotten) => Ok(forgotten),
        Err(Error::Off(_)) => {
            tracing::debug!("[flows:memory] forget skipped: memory is off");
            Ok(0)
        }
        Err(error) => Err(error),
    }
}

/// Stores `content` as `flow_id`'s value for `key`, replacing an earlier
/// value under the same key. It snapshots matching ids, stores the new value,
/// and only then forgets the old snapshot, so a failed write preserves the
/// previous value and concurrent writes after the snapshot survive. Returns
/// the stored item's id.
pub async fn remember_keyed(
    config: &Config,
    flow_id: &str,
    key: &str,
    content: &str,
    kind: LearningKind,
) -> Result<String> {
    // Fail with MEMORY_OFF before touching anything.
    crate::memory::engine::resolve(config).engine()?;
    let key_tag = flow_key_tag(flow_id, key);
    // Take a scoped snapshot before writing. If learning fails, this leaves
    // the prior value intact; deleting by these ids after learning also keeps
    // a concurrent write that was absent from the snapshot.
    let mut old_ids = Vec::new();
    let mut cursor = None;
    loop {
        let page = crate::memory::ops::items_list(
            config,
            ItemsListParams {
                filter: Some(MetaFilter::tags_any([key_tag.clone()])),
                limit: Some(MAX_LIMIT),
                cursor,
                ..ItemsListParams::default()
            },
        )
        .await?;
        old_ids.extend(page.items.into_iter().map(|item| item.id.0));
        cursor = page.next_cursor;
        if cursor.is_none() {
            break;
        }
    }
    // A flow's own key/value state: searchable, but nothing is derived from
    // it as memory about the user.
    let mut meta = flow_meta(flow_id, &[key_tag]);
    meta.derive = Some(false);
    let view = crate::memory::ops::learn(
        config,
        LearnParams {
            text: content.to_string(),
            kind: Some(kind),
            confidence: None,
            meta: None,
        },
        Some(meta),
    )
    .await?;
    let obsolete_ids: Vec<String> = old_ids.into_iter().filter(|id| id != &view.id).collect();
    let replaced = if obsolete_ids.is_empty() {
        0
    } else {
        crate::memory::ops::forget(
            config,
            ForgetParams {
                ids: obsolete_ids,
                reach: None,
            },
        )
        .await?
        .forgotten
    };
    tracing::debug!(
        flow_id = %flow_id,
        key_chars = key.chars().count(),
        content_chars = content.chars().count(),
        replaced,
        "[flows:memory] keyed flow memory stored"
    );
    Ok(view.id)
}

/// Maps the tool's `category` argument onto a learning kind.
fn learning_kind_for(category: Option<&str>) -> LearningKind {
    match category.map(|c| c.trim().to_ascii_lowercase()) {
        None => LearningKind::Fact,
        Some(c) => match c.as_str() {
            "" | "fact" | "core" => LearningKind::Fact,
            "preference" => LearningKind::Preference,
            "procedure" => LearningKind::Procedure,
            "correction" => LearningKind::Correction,
            _ => LearningKind::Other,
        },
    }
}

/// Read-only recall over a flow's own items, or (with `scope: "flows"`)
/// across every flow's items — never the user's own memory.
pub struct FlowMemoryRecallTool;

impl FlowMemoryRecallTool {
    /// Holds no memory handle — config and engine are resolved per call.
    #[must_use]
    pub fn new() -> Self {
        Self
    }
}

impl Default for FlowMemoryRecallTool {
    fn default() -> Self {
        Self::new()
    }
}

/// Renders a recall answer and its citations, each attributed to its flow
/// key when it has one.
fn render_recall(answer: &str, citations: &[Citation]) -> String {
    if citations.is_empty() {
        return "No flow memories found matching that query.".to_string();
    }
    use std::fmt::Write;
    let mut output = format!("{answer}\n\nSources ({}):\n", citations.len());
    for citation in citations {
        let key = flow_key_of(&citation.meta).unwrap_or("-");
        let _ = writeln!(output, "- [{}] [{key}] {}", citation.id.0, citation.snippet);
    }
    output
}

#[async_trait]
impl Tool for FlowMemoryRecallTool {
    fn name(&self) -> &str {
        "flow_memory_recall"
    }

    fn description(&self) -> &str {
        "Search a flow's own private memory for relevant facts — e.g. so a scheduled \
         digest flow can check what it already sent before, to avoid duplicates. `scope: \"flow\"` \
         (the default) searches only the calling flow's own memory. `scope: \"flows\"` searches \
         read-only across every flow's memory (useful when related flows should dedupe \
         against each other). This tool never reads the user's personal memory — only memory \
         flows have written about their own runs."
    }

    fn parameters_schema(&self) -> serde_json::Value {
        json!({
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "Keywords or phrase to search for"
                },
                "flow_id": {
                    "type": "string",
                    "description": "The calling flow's id. Inside a running flow this is informational \
                     only: the active flow's own id (from the run's trusted origin) is authoritative and \
                     any value supplied here is ignored. Required only when this tool is invoked outside \
                     a flow run (e.g. from a chat agent)."
                },
                "scope": {
                    "type": "string",
                    "enum": ["flow", "flows"],
                    "description": "\"flow\" (default) searches only this flow's own memory; \"flows\" searches read-only across every flow's memory."
                },
                "limit": {
                    "type": "integer",
                    "description": "Max results to return (default: 5)"
                }
            },
            "required": ["query", "flow_id"]
        })
    }

    async fn execute(&self, args: serde_json::Value) -> anyhow::Result<ToolResult> {
        self.execute_with_context(args, tinytools::ToolCallOptions::default(), None)
            .await
    }

    async fn execute_with_context(
        &self,
        args: serde_json::Value,
        _options: tinytools::ToolCallOptions,
        tool_context: Option<&dyn tinytools::ToolRunContext>,
    ) -> anyhow::Result<ToolResult> {
        let origin =
            crate::agent::tinyagents::host::run_context::turn_origin_for_tool(tool_context);
        let query = match args.get("query").and_then(|v| v.as_str()) {
            Some(q) => q.trim(),
            None => return Ok(ToolResult::error("Missing 'query' parameter".to_string())),
        };
        if query.is_empty() {
            return Ok(ToolResult::error("query cannot be empty".to_string()));
        }
        let flow_id_arg = args.get("flow_id").and_then(|v| v.as_str()).map(str::trim);

        // SECURITY: inside a running flow the trusted origin wins over the
        // model-supplied `flow_id` argument.
        let flow_id = match trusted_flow_id(origin.as_ref()) {
            Some(trusted_id) => {
                tracing::debug!(
                    target: "flows",
                    flow_id = %trusted_id,
                    "[flows:memory] flow_memory_recall: flow id from the trusted Workflow origin"
                );
                trusted_id
            }
            None => match flow_id_arg {
                None => return Ok(ToolResult::error("Missing 'flow_id' parameter".to_string())),
                Some("") => return Ok(ToolResult::error("flow_id cannot be empty".to_string())),
                Some(arg) => arg.to_string(),
            },
        };
        let scope = args.get("scope").and_then(|v| v.as_str()).unwrap_or("flow");
        let filter = match scope {
            "flow" => flow_filter(&flow_id),
            "flows" => cross_flow_filter(),
            other => {
                return Ok(ToolResult::error(format!(
                    "Unknown scope '{other}': expected 'flow' or 'flows'"
                )))
            }
        };
        #[allow(clippy::cast_possible_truncation)]
        let limit = args
            .get("limit")
            .and_then(serde_json::Value::as_u64)
            .map_or(5, |v| v as usize);

        let config =
            match crate::agent::tinyagents::host::run_context::dispatch_ctx_for_tool(tool_context)
                .load_config()
                .await
            {
                Ok(config) => config,
                Err(error) => {
                    return Ok(ToolResult::error(format!(
                        "Flow memory recall failed: {error}"
                    )))
                }
            };
        tracing::debug!(
            target: "flows",
            scope,
            query_chars = query.chars().count(),
            limit,
            "[flows:memory] flow_memory_recall: querying"
        );
        match crate::memory::ops::recall(
            &config,
            RecallParams {
                refers_to: None,
                question: query.to_string(),
                filter: Some(filter),
                limit: Some(limit),
            },
        )
        .await
        {
            Ok(view) => {
                tracing::debug!(
                    target: "flows",
                    scope,
                    citations = view.citations.len(),
                    "[flows:memory] flow_memory_recall: answered"
                );
                Ok(ToolResult::success(render_recall(
                    &view.answer,
                    &view.citations,
                )))
            }
            Err(error) => {
                tracing::debug!(
                    target: "flows",
                    code = error.code(),
                    "[flows:memory] flow_memory_recall: failed"
                );
                Ok(ToolResult::error(format!(
                    "Flow memory recall failed: {error}"
                )))
            }
        }
    }

    fn is_concurrency_safe(&self, _args: &serde_json::Value) -> bool {
        true
    }
}

/// Write access to a flow's own memory — and *only* its own. See the module
/// doc for the security invariant this tool exists to preserve.
pub struct FlowMemoryRememberTool {
    security: Arc<SecurityPolicy>,
}

impl FlowMemoryRememberTool {
    /// Holds no memory handle — config and engine are resolved per call.
    #[must_use]
    pub fn new(security: Arc<SecurityPolicy>) -> Self {
        Self { security }
    }
}

#[async_trait]
impl Tool for FlowMemoryRememberTool {
    fn name(&self) -> &str {
        "flow_memory_remember"
    }

    fn description(&self) -> &str {
        "Store a fact in THIS flow's own private memory — e.g. so a scheduled digest \
         flow can remember which items it already sent, to avoid re-sending them on the next run. \
         Writing the same `key` again replaces the earlier value. The flow is taken from the run \
         itself; there is no way to target the user's personal memory or another flow's memory \
         from this tool."
    }

    fn parameters_schema(&self) -> serde_json::Value {
        static_schema!(include_str!("parameters/flow_memory_remember.json"))
    }

    fn permission_level(&self) -> PermissionLevel {
        PermissionLevel::Write
    }

    async fn execute(&self, args: serde_json::Value) -> anyhow::Result<ToolResult> {
        self.execute_with_context(args, tinytools::ToolCallOptions::default(), None)
            .await
    }

    async fn execute_with_context(
        &self,
        args: serde_json::Value,
        _options: tinytools::ToolCallOptions,
        tool_context: Option<&dyn tinytools::ToolRunContext>,
    ) -> anyhow::Result<ToolResult> {
        let origin =
            crate::agent::tinyagents::host::run_context::turn_origin_for_tool(tool_context);
        let flow_id_arg = args.get("flow_id").and_then(|v| v.as_str());
        let Some(key) = args.get("key").and_then(|v| v.as_str()) else {
            return Ok(ToolResult::error("Missing 'key' parameter".to_string()));
        };
        let Some(content) = args.get("content").and_then(|v| v.as_str()) else {
            return Ok(ToolResult::error("Missing 'content' parameter".to_string()));
        };
        let kind = learning_kind_for(args.get("category").and_then(|v| v.as_str()));

        if let Err(error) = self
            .security
            .enforce_tool_operation(ToolOperation::Act, "flow_memory_remember")
        {
            return Ok(ToolResult::error(error));
        }

        // SECURITY (T-M2): the flow comes from the trusted run origin only;
        // outside a workflow run the write is refused.
        let Some(flow_id) = trusted_flow_id(origin.as_ref()) else {
            tracing::warn!(
                target: "flows",
                requested_flow_id_chars = flow_id_arg.map_or(0, str::len),
                "[flows:memory:security] flow_memory_remember refused: no trusted Workflow run origin"
            );
            return Ok(ToolResult::error(
                "flow memory writes are only available inside a workflow run".to_string(),
            ));
        };
        let key = key.trim();
        if key.is_empty() {
            return Ok(ToolResult::error("key cannot be empty".to_string()));
        }
        if tinyredact::has_likely_secret(content) {
            tracing::warn!(
                target: "flows",
                key_chars = key.chars().count(),
                content_chars = content.chars().count(),
                "[flows:memory:safety] flow_memory_remember rejected secret-like content"
            );
            return Ok(ToolResult::error(
                "Refusing to store content that looks like a secret. Remove credentials or tokens and try again.".to_string(),
            ));
        }

        let config =
            match crate::agent::tinyagents::host::run_context::dispatch_ctx_for_tool(tool_context)
                .load_config()
                .await
            {
                Ok(config) => config,
                Err(error) => {
                    return Ok(ToolResult::error(format!(
                        "Failed to store flow memory: {error}"
                    )))
                }
            };
        match remember_keyed(&config, &flow_id, key, content, kind).await {
            Ok(_) => Ok(ToolResult::success(format!("Stored flow memory: {key}"))),
            Err(error) => {
                tracing::debug!(
                    target: "flows",
                    code = error.code(),
                    "[flows:memory] flow_memory_remember: store failed"
                );
                Ok(ToolResult::error(format!(
                    "Failed to store flow memory: {error}"
                )))
            }
        }
    }
}

#[cfg(test)]
#[path = "memory_tools_tests.rs"]
mod tests;

#[cfg(test)]
#[path = "memory_tools_schema_tests.rs"]
mod schema_tests;