agentmux_srv/server/app_api/bundle/

components.rs

// Copyright 2026, AgentMux Corp.
// SPDX-License-Identifier: Apache-2.0

//! Component plumbing shared by the per-agent export and import paths:
//! purging dangling component refs, resolving a bundle's components to their
//! backing rows, and splicing history/instructions/memory into a manifest.

use super::*;

/// Drop a deleted bundle's component refs.
///
/// Called from **both** delete paths — `bundle.delete` here and `deletememory`
/// in `agent_handlers/bundle.rs`, which is the one Memory actually calls.
/// Fixing only the first left the product path orphaning refs (Codex, PR
/// #3153), so this exists to make "both" mean one implementation.
///
/// `bundle_delete` runs on the store that owns `db_bundles`, which has no ref
/// tables — they live in the channel store, a different database, which is
/// also why no foreign key reaches across (the `db_bundle_skills_ref` comment
/// in `migrations.rs`'s `run_object_schema`). So the purge cannot live inside
/// it and has to be driven from a handler, where both stores are in scope.
///
/// Best-effort by design: the bundle row is already gone by the time this
/// runs, so a failure here must not turn a successful delete into an error.
pub(crate) fn purge_bundle_component_refs(
    mstore: &crate::backend::storage::store::Store,
    bundle_id: &str,
) {
    match mstore.bundle_unbind_all_components(bundle_id) {
        Ok((skills, mcp)) if skills + mcp > 0 => {
            tracing::info!(bundle_id, skills, mcp, "bundle delete: purged component refs")
        }
        Ok(_) => {}
        Err(e) => tracing::warn!(
            bundle_id, error = %e,
            "bundle delete: component refs left behind"
        ),
    }
    // And out of this channel's agents' Bundles lists; a list on another
    // channel skips it at launch.
    if let Err(e) = mstore.agent_bundles_forget_bundle(bundle_id) {
        tracing::warn!(bundle_id, error = %e, "bundle delete: left in agents' Bundles lists");
    }
}

/// Bind an imported bundle's skills into the ref table.
///
/// Phase 0b. The ref tables are authoritative for what a bundle contains, so
/// an import that only wrote the inline column would produce a bundle that
/// exports empty.
///
/// **Must run after `bundle_upsert`.** The bind checks the bundle exists in
/// `id_store` first (`managed_bind_bundle` in `storage/managed.rs`) and
/// refuses otherwise.
///
/// Returns warnings rather than failing: by this point the bundle row is
/// already committed, so aborting would leave a half-imported bundle behind. A
/// component that could not be bound is reported and the import continues.
pub(super) fn bind_imported_components(
    mstore: &crate::backend::storage::store::Store,
    id_store: &crate::backend::storage::store::Store,
    identity_store: &crate::backend::storage::store::Store,
    bundle_id: &str,
    imported_skill_ids: &[String],
) -> Vec<String> {
    let mut warnings: Vec<String> = Vec::new();

    for skill_id in imported_skill_ids {
        if let Err(e) = mstore.bundle_skill_bind(identity_store, id_store, bundle_id, skill_id) {
            warnings.push(format!(
                "skills: imported skill {skill_id} could not be bound to the bundle ({e}) — it will not be exported or reach the agent"
            ));
        }
    }

    warnings
}

/// The warning an import gives for the MCP servers an archive carries. A
/// bundle carries no MCP servers, so none is imported; they're named so the
/// user can add them in Connectors
/// (`SPEC_BUNDLE_CONTENTS_MEMORY_NOT_MCP_2026_10_07.md` §3.1). `None` when
/// the archive has none.
pub(crate) fn mcp_servers_not_imported_warning(
    servers: &[crate::backend::bundle_import::ParsedMcpServer],
) -> Option<String> {
    if servers.is_empty() {
        return None;
    }
    let names: Vec<String> = servers
        .iter()
        .map(|m| {
            crate::backend::bundle_import::mcp_server_display(&m.config)
                .get("name")
                .and_then(|v| v.as_str())
                .map(str::to_string)
                .unwrap_or_else(|| m.source_path.clone())
        })
        .collect();
    Some(format!(
        "mcpServers: not imported ({}). Bundles don't carry MCP servers; add them in Connectors",
        names.join(", ")
    ))
}

/// A bundle's components, resolved from the tables that are authoritative for
/// them.
pub(crate) struct ResolvedComponents {
    pub(crate) skills: Vec<crate::backend::storage::Skill>,
}

/// Resolve what a bundle actually contains, from `db_bundle_skills_ref`.
///
/// Phase 0b of `SPEC_INSTRUCTION_AND_MEMORY_PORTABILITY_2026_09_09.md`. Before
/// this, export read the inline `bundle.skills` column
/// while agent launch read the ref tables (`write_agent_config_files` in
/// `app_api/agent_open.rs`), and nothing kept the two in step — so a skill
/// bound in Memory → Skills ran at launch but exported as an empty `skills/`
/// directory, with no warning. One
/// resolver, used by every export path, is what stops that recurring.
///
/// **Scope note:** this is deliberately narrower than `effective_skills`,
/// which additionally unions an *agent's* own binds, globals and the legacy
/// blob. Those answer "what does this agent run with";
/// this answers "what is in this bundle", which is what an ABF describes. The
/// two are not meant to be equal, only to agree about the bundle's own
/// contribution.
///
/// `managed_list` returns the whole catalog with a `bound_to_bundle` flag
/// rather than just the bound rows, hence the filter; and because it joins
/// through the catalog table, a ref whose catalog row has been deleted
/// resolves to nothing rather than reporting itself. `skill_delete` purges
/// refs (`managed_delete` in
/// `storage/managed.rs`), so that state is not reachable through the app
/// within one channel — but no FK enforces it: the ref tables' catalog FK was
/// dropped in schema v34, once the catalog moved to `identity_store`.
pub(crate) fn resolve_bundle_components(
    mstore: &crate::backend::storage::store::Store,
    identity_store: &crate::backend::storage::store::Store,
    bundle_id: &str,
) -> Result<ResolvedComponents, String> {
    let skills: Vec<crate::backend::storage::Skill> = mstore
        .bundle_skill_list(identity_store, bundle_id)
        .map_err(|e| format!("failed to resolve bundle skills: {e}"))?
        .into_iter()
        .filter(|item| item.bound_to_bundle)
        .map(|item| item.skill)
        .collect();
    Ok(ResolvedComponents { skills })
}

/// Warning the agent-less `bundle.export` pushes when the bundle it is
/// exporting is bound to an agent that actually has native memory.
///
/// Mirror of [`crate::backend::bundle_import::MEMORY_COMPONENT_IGNORED_WARNING`]
/// on the import side, and a constant for the same reason that one is: the push
/// site and the test that pins the wording must not drift apart.
///
/// `SPEC_INSTRUCTION_AND_MEMORY_PORTABILITY_2026_09_09.md` §3.1/§5.1. The
/// asymmetry worth fixing was never that `bundle.export` omits memory — a
/// bundle detached from any agent has no memory to carry, and omitting it is
/// correct. It is that import *announces* the omission and export did not,
/// while every `components` key is optional (`export_bundle` in
/// `bundle_export.rs` inserts each only when non-empty), so a missing `memory`
/// key is indistinguishable from "this bundle had none".
pub(crate) const MEMORY_NOT_EXPORTED_WARNING: &str =
    "memory: this bundle is bound to an agent with native memory, which bundle.export does not carry — use bundle.export_for_agent to include it";

/// Does any agent bound to `bundle_id` have mirrored native memory?
///
/// **Both bindings count.** A bundle is reachable two ways, and they are
/// different columns: `AgentDefinition.memory_id` is the agent's own dedicated
/// bundle (stored in `db_agents.default_memory_id`), while
/// `AgentInstance.memory_id` is one *launch* deliberately pointed at some other
/// bundle (`AgentDefinition::memory_id` in `storage/agents/mod.rs`). Checking only
/// the definition would miss exactly the case the operator is most likely to
/// hit — exporting the bundle a running instance was launched with. Native memory is keyed on the
/// definition id either way (`build_export_for_agent` resolves the agent with
/// `agent_def_get` before reading memory), so the instance path resolves
/// through `definition_id`.
///
/// Reads the `db_agent_native_memory` mirror and deliberately does NOT call
/// `refresh_memory_mirror_from_live_fs` first, unlike `build_export_for_agent`
/// (which must, because it is about to *copy* the files —
/// `app_api/bundle/export_for_agent.rs`). Refreshing writes to the store, and
/// an agent-less export has no business mutating per-agent state as a side
/// effect of producing a warning.
///
/// **Known limitation — a cross-channel binding is invisible here, and cannot
/// currently be made visible.** Both lookups resolve the binding from
/// channel-local SQLite: `instance_list` reads this channel's rows, and
/// `agent_def_list`'s global overlay only preserves `memory_id` when a local
/// row exists (`agent_def_list` in `storage/agents/definition.rs`). An agent created in
/// another channel has no local row, so it comes back with an empty
/// `memory_id` — because `DefinitionRecordV1` does not carry the field at all
/// (`record_to_agent_definition` in `storage/def_registry_mirror.rs`). The
/// bundle and the memory mirror are global; only the binding between them is not. So exporting a shared
/// bundle from a channel other than the one its agent was created in will not
/// warn, which is exactly the portability case the warning is for (Codex, PR
/// #3147).
///
/// Closing it means adding `memory_id` to the registry wire format, which is
/// already a tracked gap for bigger reasons than this warning — the same
/// missing field makes a cross-channel reopen start unbound and limits m0021's
/// backfill to local SQLite. Tracked in #3148; deliberately not widened here,
/// because warning whenever the binding is merely *unknown* would fire on
/// unrelated bundles and train operators to ignore it.
///
/// The other cost is under-warning on a stale mirror: an agent whose memory
/// exists on disk but was never mirrored is missed. That is the residual gap
/// `SPEC_NATIVE_MEMORY_DURABLE_SYNC_2026_08_07.md` already documents and
/// accepts for the mirror generally. Both costs are one-directional and this
/// warning is advisory — it changes no bytes in the archive.
pub(super) fn bound_agent_has_native_memory(
    id_store: &crate::backend::storage::store::Store,
    mstore: &crate::backend::storage::store::Store,
    bundle_id: &str,
) -> bool {
    // A blank bundle_id is the "blank singleton" sentinel that every unbound
    // agent carries — treating it as a binding would warn on nearly every
    // export.
    if bundle_id.is_empty() {
        return false;
    }

    let has_memory = |agent_id: &str| {
        id_store
            .agent_native_memory_list_meta(agent_id)
            .map(|rows| !rows.is_empty())
            .unwrap_or(false)
    };

    // Best-effort throughout: a store error here must not fail an export that
    // is otherwise fine. Neither table is read by the export itself.
    let bound_by_definition = mstore
        .agent_def_list()
        .map(|agents| {
            agents
                .iter()
                .filter(|a| a.memory_id == bundle_id)
                .any(|a| has_memory(&a.id))
        })
        .unwrap_or(false);
    if bound_by_definition {
        return true;
    }

    mstore
        .instance_list(None, None)
        .map(|instances| {
            instances
                .iter()
                .filter(|i| i.memory_id == bundle_id)
                .any(|i| has_memory(&i.definition_id))
        })
        .unwrap_or(false)
}

/// Register `entries` under `components.<key>` in the export's manifest (`bundle.json`).
///
/// Takes JSON values rather than paths: most components are a list of archive
/// paths, but `projectInstructions` carries an object per file, because a bare
/// path could not express the `owner` discriminator that keeps import from
/// installing somebody else's instructions.
///
/// The manifest is built as an inline `json!` literal in `bundle_export.rs`
/// with no struct behind it (`export_bundle`), so every agent-aware
/// component has to reopen and rewrite it. Shared by the memory splice below
/// and the history splice, which otherwise duplicated the find-parse-rewrite
/// dance byte for byte.
///
/// No-ops on an empty list: `components` keys are all optional, and writing
/// `"history": []` would assert "this archive has an empty history" where
/// absence already says "none".
pub(super) fn set_manifest_component(
    export: &mut crate::backend::bundle_export::BundleExport,
    key: &str,
    entries: Vec<serde_json::Value>,
) -> Result<(), String> {
    if entries.is_empty() {
        return Ok(());
    }
    let manifest_name = crate::backend::bundle_import::manifest_file_name(|n| export.files.iter().any(|f| f.path == n))
        .ok_or_else(|| "bundle export has no manifest".to_string())?;
    let manifest_idx = export.files.iter().position(|f| f.path == manifest_name).expect("found above");
    let mut manifest: serde_json::Value = serde_json::from_str(&export.files[manifest_idx].content)
        .map_err(|e| format!("{manifest_name}: {e}"))?;
    manifest["components"][key] = json!(entries);
    export.files[manifest_idx].content =
        serde_json::to_string_pretty(&manifest).map_err(|e| e.to_string())?;
    Ok(())
}

/// Register the transcript files `bundle.export_for_agent_with_history` already
/// wrote into the archive under `components.history`.
///
/// `SPEC_INSTRUCTION_AND_MEMORY_PORTABILITY_2026_09_09.md` §3.5: the files were
/// pushed into `export.files` (`app_api/bundle/export_for_agent.rs`) and
/// counted in the RPC response, but the manifest was never touched after the
/// memory splice — so a
/// consumer reading `components.*` to learn what an archive holds could not see
/// history at all. The paths are caller-supplied rather than re-derived here so
/// this cannot drift from what was actually written.
pub(super) fn splice_history_component(
    export: &mut crate::backend::bundle_export::BundleExport,
    history_paths: Vec<String>,
) -> Result<(), String> {
    set_manifest_component(export, "history", history_paths.into_iter().map(|p| json!(p)).collect())
}

/// Splice native-memory files into an already-built bundle export's
/// `bundle.json` manifest and files list, adding `components.memory` (ABF
/// v0.2 §2.3). Kept OUTSIDE `bundle_export.rs` deliberately — that
/// module's `export_bundle()` is scoped to a bundle's own components
/// (instructions/skills/MCP/accounts) with no concept of "agent" or
/// native memory at all; memory is agent-scoped, not bundle-scoped, so
/// splicing it in here (the RPC-handler layer, which already resolves
/// other agent-scoped data like skill rows) keeps that module's
/// documented scope intact rather than growing it a fifth, unrelated
/// component category. A no-op when `memory_files` is empty — matches the
/// existing omit-empty-components convention used elsewhere in the
/// manifest.
/// Carry the agent's project instructions into the export as
/// `components.projectInstructions`.
///
/// Phase 3 of `SPEC_INSTRUCTION_AND_MEMORY_PORTABILITY_2026_09_09.md`. Files
/// land under `instructions/project/<sanitized-path>`, and each manifest entry
/// carries its original `path`, a `contentHash`, and an `owner`.
///
/// **`owner` is the load-bearing field.** It is what stops this from becoming a
/// way to install one repository's instructions into another: an importer that
/// treated a `foreign` entry as content to write would be doing precisely what
/// `SPEC_CLAUDE_MD_OWNERSHIP_PROTECTION_2026_08_22.md` exists to prevent.
/// Import surfaces these and never applies them (spec §5.2), so an operator who
/// wants them acts deliberately.
///
/// Only files that exist and were readable are carried — there is nothing to
/// put in an archive otherwise. Their absence from the manifest is therefore
/// not a claim that the source agent had none; `agent.project_instructions` is
/// where the fuller picture, including absent and unreadable files, lives.
///
/// "Readable" is decided by `error`/`truncated`, NOT by whether the content is
/// empty (Codex P2, PR #3163). A real, readable, zero-byte `CLAUDE.md` is a
/// fact about the source agent — dropping it would make the export
/// indistinguishable from one where the file was absent, which is the exact
/// kind of quiet lie this component exists to remove.
///
/// Paths go through the same sanitizer the exporter uses for context files, so
/// a scanned path can never write outside the archive's own tree.
pub(super) fn splice_project_instructions_component(
    export: &mut crate::backend::bundle_export::BundleExport,
    files: &[crate::backend::project_instructions::ProjectInstructionFile],
) -> Result<(), String> {
    use crate::backend::project_instructions::InstructionOwner;
    use std::collections::HashSet;

    let mut entries: Vec<serde_json::Value> = Vec::new();
    // Case-INSENSITIVE, for the same reason the context-file loop in
    // `bundle_export.rs` is (reagent P2, PR #2333): a case-sensitive source
    // filesystem can hold `.github/instructions/A.md` and `.../a.md`, and the
    // scan in `project_instructions.rs` will find both — but they collide on
    // extraction on Windows/macOS, where one snapshot silently overwrites the
    // other. Scanned directories make this reachable here in a way it isn't
    // for the fixed registry paths (Codex P2, PR #3163). The written path
    // keeps its original case; only the check is folded.
    let mut used_paths: HashSet<String> = HashSet::new();
    for file in files {
        if !file.exists || file.error.is_some() || file.truncated {
            continue;
        }
        let Some(safe) = crate::backend::bundle_export::sanitize_context_relative_path(&file.path)
        else {
            // Warn rather than dropping in silence — a backup tool that loses
            // an input without saying so defeats its own purpose (reagent P1,
            // PR #2333, on the context-file equivalent).
            export.warnings.push(format!(
                "projectInstructions: \"{}\" could not be sanitized into an \
                 archive-relative path; skipped",
                file.path
            ));
            continue;
        };
        let out_path = format!("instructions/project/{safe}");
        if !used_paths.insert(out_path.to_lowercase()) {
            export.warnings.push(format!(
                "projectInstructions: \"{}\" normalizes to the same path as an \
                 earlier entry ({out_path}); skipped to avoid overwriting it",
                file.path
            ));
            continue;
        }
        export.files.push(crate::backend::bundle_export::BundleExportFile {
            path: out_path.clone(),
            content: file.content.clone(),
        });
        entries.push(json!({
            "path": file.path,
            "file": out_path,
            "contentHash": file.content_hash,
            "owner": match file.owner {
                InstructionOwner::Agentmux => "agentmux",
                InstructionOwner::Foreign => "foreign",
            },
        }));
    }
    set_manifest_component(export, "projectInstructions", entries)
}

pub(super) fn splice_memory_component(
    export: &mut crate::backend::bundle_export::BundleExport,
    memory_files: &[(String, String)],
) -> Result<(), String> {
    if memory_files.is_empty() {
        return Ok(());
    }
    let mut manifest_memory: Vec<String> = Vec::new();
    for (filename, content) in memory_files {
        // Filenames here always came from db_agent_native_memory, which
        // only ever accepts app-validated names (validate_filename in
        // native_memory_handlers.rs: alphanumeric + "-_", ends ".md", no
        // separators) — unlike instructions_by_provider's keys (§2.2),
        // there's no untrusted-manifest path that could smuggle an unsafe
        // segment in here, so no additional sanitization is needed.
        let out_path = format!("memory/{filename}");
        export.files.push(crate::backend::bundle_export::BundleExportFile {
            path: out_path.clone(),
            content: content.clone(),
        });
        manifest_memory.push(out_path);
    }
    set_manifest_component(export, "memory", manifest_memory.into_iter().map(|p| json!(p)).collect())
}